Treehopper C# API
ConnectionService Class Referenceabstract

Discovers Treehopper boards attached to your device. More...

Inheritance diagram for ConnectionService:

Main components

static ConnectionService Instance [get]
 The singleton instance through which to access ConnectionService. More...
 
ObservableCollection< TreehopperUsbBoards [get]
 The Treehopper boards attached to the computer. More...
 
Task< TreehopperUsbGetFirstDeviceAsync ()
 Get a reference to the first device discovered. More...
 

Treehopper.Desktop-specific properties

static bool IsWindows [get]
 Determines if executing in Windows More...
 
static bool IsLinux [get]
 Determines if we're running in Linux More...
 
static bool IsMac [get]
 Determines if we're running in macOS More...
 
abstract void Dispose ()
 Dispose this ConnectionService to close device watchers and clean up resources More...
 

Xamarin.Android Methods

UsbManager Manager [get]
 
void ActivityOnStart (Activity activity)
 Call this method in your main activity's OnStart() override. More...
 
void ActivityOnResume ()
 Call this method in your main activity's OnResume() override. More...
 

Detailed Description

Discovers Treehopper boards attached to your device.

This documentation set covers the ConnectionService class found in Treehopper.Desktop, Treehopper.Android, and Treehopper.Uwp packages.

Note
ConnectionService should always be accessed through its singleton property, ConnectionService.Instance. Do not create instances of ConnectionService yourself.

Basic usage

When running in .NET Core, .NET Framework, Mono, or Windows 10 UWP, no additional configuration is needed.

There are two ways to access discovered boards. If you simply want to wait until the first Treehopper board is attached to the computer, the GetFirstDeviceAsync() method will return an awaitable task with a result that contains the board:

var board = await ConnectionService.Instance.GetFirstDeviceAsync();

Advanced usage

For simple applications, you can retrieve a board instance with GetFirstDeviceAsync(), however, if you'd like to present the user with a list of devices from which to choose, you can reference the Boards property.

Warning
Even if you already have a board connected, the Boards collection is not guaranteed to have a board populated on first invocation. Board discovery on many platforms is done asynchronously, so you should always bind to the CollectionChanged event of this collection to get notified when boards are added.

GUI apps or more advanced console apps can query or bind directly to the Boards property, which is an ObservableCollection that can notify when boards are attached or removed:

ConnectionService.Instance.Boards.CollectionChanged += async(o, e) => {
if(e.NewItems.Count > 0) // a new board was added
RunApp((TreehopperUsb)e.NewItems[0])
};
// if we already have a board in the collection, start the app
if(ConnectionService.Instance.Boards.Count > 0)
RunApp(ConnectionService.Instance.Boards[0]);
Warning
After subscribing to CollectionChanged, you should always check the collection. A board may have already been added before you subscribed to the CollectionChanged event, and the event will not re-fire for new subscribers.

Xamarin.Android

To integrate Treehopper into a Xamarin Android-based project, you must integrate ConnectionService calls into your activity's implementation.

To do this, call the ActivityOnStart() and ActivityOnResume() methods in their respective overrides, like so:

protected override void OnStart()
{
base.OnStart();
ConnectionService.Instance.ActivityOnStart(this);
ConnectionService.Instance.Boards.CollectionChanged += Boards_CollectionChanged;
}
private void Boards_CollectionChanged(object sender, System.Collections.Specialized.NotifyCollectionChangedEventArgs e)
{
// handle board attach/detached events here
}
protected override void OnResume()
{
base.OnResume();
ConnectionService.Instance.ActivityOnResume();
}

Member Function Documentation

◆ GetFirstDeviceAsync()

Task<TreehopperUsb> GetFirstDeviceAsync ( )

Get a reference to the first device discovered.

Returns
The first board found.

If no devices have been plugged into the computer, this call will await indefinitely until a board is plugged in.

◆ Dispose()

abstract void Dispose ( )
pure virtual

Dispose this ConnectionService to close device watchers and clean up resources

◆ ActivityOnStart()

void ActivityOnStart ( Activity  activity)

Call this method in your main activity's OnStart() override.

Parameters
activity

◆ ActivityOnResume()

void ActivityOnResume ( )

Call this method in your main activity's OnResume() override.

Property Documentation

◆ Instance

ConnectionService Instance
staticget

The singleton instance through which to access ConnectionService.

This instance is created and started upon the first reference to a property or method on this object. This typically only becomes an issue if you expect to have debug messages from ConnectionService printing even if you haven't actually accessed the object yet.

◆ Boards

ObservableCollection<TreehopperUsb> Boards
get

The Treehopper boards attached to the computer.

For simple applications, you can retrieve a board instance with GetFirstDeviceAsync(), however, if you'd like to present the user with a list of devices from which to choose, you can reference this property.

    \warning Even if you already have a board connected to your device when you first invoke this property, this collection is not guaranteed to have a board populated on first invocation. Board discovery on many platforms is done asynchronously, so you should always bind to the [CollectionChanged](https://docs.microsoft.com/en-us/dotnet/api/system.collections.objectmodel.observablecollection-1.collectionchanged?view=netframework-4.7.1) event of this collection to get notified when boards are added.

    GUI apps or more advanced console apps can query or bind directly to the #Boards property, which is an ObservableCollection that can notify when boards are attached or removed:

    ```
    ConnectionService.Instance.Boards.CollectionChanged += async(o, e) => {
            if(e.NewItems.Count > 0) // a new board was added
                RunApp((TreehopperUsb)e.NewItems[0])
        };

if we already have a board in the collection, start the app if(ConnectionService.Instance.Boards.Count > 0) RunApp(ConnectionService.Instance.Boards[0]);

```

Warning
After subscribing to CollectionChanged, you should always check the collection. A board may have already been added before you subscribed to the CollectionChanged event, and the event will not re-fire for new subscribers.

◆ IsWindows

bool IsWindows
staticget

Determines if executing in Windows

◆ IsLinux

bool IsLinux
staticget

Determines if we're running in Linux

◆ IsMac

bool IsMac
staticget

Determines if we're running in macOS

◆ Manager

UsbManager Manager
get

The documentation for this class was generated from the following file: