A developer's introduction to ConnMan

ConnMan is the connectivity daemon used in Moblin, used to manage and monitor the state of network connections. It is an extremely flexible, extensible and developer-friendly product.

This tutorial explains how to interact programmatically with the ConnMan connectivity daemon. It shows how to interact with ConnMan via its D-Bus interface and also very briefly covers extending ConnMan with plugins. It doesn't cover specifics of interacting with D-Bus APIs, as that topic is generic enough to be covered separately. However, it does introduce the D-Bus API as exposed by ConnMan.

ConnMan's D-Bus API

ConnMan differs from most D-Bus APIs in that the objects it exposes don't implement the org.freedesktop.DBus.Properties interface. Instead, the interfaces defined by ConnMan implement their own GetProperties and SetProperty methods. This is so that the properties can provide change notification via signals (which is not possbile using the standard D-Bus Properties interface).

The components of ConnMan's D-Bus API are described in the following sub-sections.

Service API - high level UI API

The Service API defines high-level network services implemented through the org.moblin.connman.Manager and org.moblin.connman.Service interfaces. It is possible to write a complete connectivity UI using the Service API, as is done in the Moblin Netbook UX.

A single object implementing the Manager interface exists on the connman path, through this one can retrieve a list of Service objects (as well as Devices, Profiles and Connections as discussed later).

org.moblin.connman.Manager

The Manager interface defines many methods, signals and properties, but the most important ones are:

Properties

State (read-only): Global state of the system (online, connected or offline).

AvailableTechnologies (read-only): Array of technologies available on the system (wifi, ethernet, wimax, cellular, bluetooth).

EnabledTechnologies (read-only): Array of enabled technologies (a subset of AvailableTechnologies).

ConnectedTechnologies (read-only): Array of technologies with an active connection (a subset of AvailableTechnologies).

OfflineMode (read-write): Boolean representing whether offline mode is enabled.

Services (read-only): Sorted array of object paths of available Services objects.

Methods

GetProperties(): Returns a dictionary mapping property names to current values for each property of the object.

SetProperty(string name, variant value): Sets the value for the named property.

GetState(): A convenience method for applications which want to know the daemon state, but don't care about the rest of the properties.

RequestScan(string type): Triggers a network scan for technology type; passing an empty string to this method performs a trigger scan on all supported technologies.

EnableTechnology(string type) / DisableTechnology(string type): Used to enable/disable technologies. The argument passed to this method specifies the type of technology to enable/disable. This method will also appropriately set the powered state of the device.

ConnectService(dict network): Connect to a service as specified by the properties in the network dictionary. Typically used for connecting to hidden networks. For example, to connect to a hidden WiFi network, the network argument passed in might look like this:

Signals

PropertyChanged: Signal emitted when one of the object's properties has changed.

StateChanged: A convenience signal implemented solely to notify when the State property changes. Useful if an application only cares about whether the system is online or not, but needs to be notified when that state changes.

org.moblin.connman.Service

The Service interface provides a high-level network object with methods for setting up, connecting and disconnecting. The most notable methods, properties and signals of the Service interface are:

Properties

State (read-only): The status of the service as a string. Possible values are "idle", "failure", "association", "configuration", and "ready". The State is "ready" when the service is usable for connectivity.

Error (read-only): When the service state is "failure", this property may contain a string explaining the cause of the failure.

Security (read-only): The type of security for a wireless network. Possible values are "none", "wep", "wpa", and "rsn".

Passphrase (read-write): The passphrase of the service.

Methods

GetProperties(): Returns a dictionary mapping property names to current values for each property of the object.

SetProperty(string name, variant value): Sets the value for the named property.

Connect() / Disconnect(): Connect or disconnect the service. For services which require configuration (secure wifi, cellular, etc.), configuration must be set before a call to Connect will succeed.

Also note that the Connect method is a blocking method, so it may be wise to set a long timeout on these calls.

Remove(): Removes the service's saved state such that it will need configuration before it can be connected again. Disconnects the network (if required), clears the favourite and autoconnect flags, and clears any stored passphrase.

MoveBefore(object service): To prioritise one connected Service over another, call the MoveBefore method, passing in the object path of another Service object you want this Service object to have priority over.

Signals

PropertyChanged: Signal emitted when one of the object's properties has changed.

Devices, Connections, Profiles, etc. - low level API

The Manager interface provides access to Devices, Connections and Profiles, if you need lower-level access than that provided by the Service API. These low-level interfaces are exposed, much like Services, as arrays of object paths in the Manager interface's properties.

Knowing Whether the Device is Online

Apart from writing full connectivity UIs, a primary usage of the ConnMan D-Bus API is for detecting when the device has a usable internet connection.

For this purpose you need simply use the GetState() method and StateChanged signals of the org.moblin.connman.Manager interface.

An example showing the former, but missing out the latter for brevity, can be seen in a dbus-glib example of the moblin-sdk-samples repository: amionline.c.

Extending ConnMan with Plugins

ConnMan provides a plugin API for extending the core daemon. The ConnMan design is very modular, and in fact much of ConnMan's core functionality is implemented using this plugin API.

The plugin API is very low level, modelled on the Linux kernel's module API. It is simply a macro to which you must pass two callback implementations:

1. init: This callback is executed as the daemon starts and loads the plugin.
2. exit: This callback is executed as the daemon shuts down and unloads its plugins.

An example plugin (which does nothing) in C code:

The plugin API is very flexible: all you need provide are set-up and tear-down methods for your plugin which are called as the daemon is started and stopped (respectively).