The basic idea is that Connection Manager maintains a single flat and sorted
list of all available, preferred or previously used services. A service here
-can be either a Ethernet device, a WiFi network, a WiMAX service provider
-or a remote Bluetooth device (for example a mobile phone).
+can be either a Ethernet device, a WiFi network or a remote Bluetooth device
+(for example a mobile phone).
This list of service is sorted by Connection Manager and there is no need
for the user interface to implement its own sorting. User decisions will
+---------------------------------------+
| My WiFi AP (strength 80, rsn) |
+---------------------------------------+
- | Clear WiMAX (strength 70) |
- +---------------------------------------+
| Other AP (strength 70, rsn) |
+---------------------------------------+
| Friends AP (strength 70, wep) |
+---------------------------------------+
- | Other WiMAX (strength 50) |
- +---------------------------------------+
-If non of the services has been used before the sorting order will be done
+If none of the services has been used before the sorting order will be done
with these priorities:
1. Ethernet (lower index numbers first)
2. Bluetooth (last used devices first)
3. GSM/UTMS/3G (if SIM card is present, activated and not roaming)
- 3. WiFi/WiMAX (signal strength first, then prefer WiMAX over WiFi,
- then more secure network first)
+ 3. WiFi (signal strength first, then more secure network
+ first)
The Ethernet devices are always sorted first since they are physically built
into the system and will be always present. In cases they are switched off
in Bluetooth is too expensive. The choice here is to sort the last used
Bluetooth device before the others.
-The WiFi and WiMAX networks are treated equally since both provide signal
-strength information and networks closer in the proximity should be shown
-before others since it is more likely they are selected first. The signal
-strength value is normalized to 0-100 (effectively a percentage) and allows
-an easy sorting.
-
-If the signal strength is identical than the WiMAX network should be shown
-first since it is a licensed spectrum and more reliable. Also the number
-of WiMAX networks will be smaller than the number of WiFi since that operates
-in an unlicensed spectrum.
+WiFi networks closer in the proximity should be shown first since it is more
+likely they are selected. The signal strength value is normalized to 0-100
+(effectively a percentage) and allows an easy sorting.
-WiFi networks with the same signal strength are then sorted by its security
+WiFi networks with the same signal strength are then sorted by their security
setting. WPA2 encrypted networks should be preferred over WPA/WEP and also
unencrypted ones. After that they will be sorted by the SSID in alphabetical
order.
In the case the WiFi network uses WPS for setup and it is clearly detectable
that a network waits for Connection Manager to connect to it (for example via
a push-to-connect button press on the AP), then this network should be shown
-first before any other WiFi or WiMAX network. The reason here is that the
-user already made a choice via the access point. However this depends on
-technical details if it is possible to detect these situations.
+first before any other WiFi networks. The reason here is that the user already
+made a choice via the access point. However this depends on technical details
+if it is possible to detect these situations.
Service order
Selecting the "My WiFi AP" and successfully connecting to it makes it a
favorite device and it will become an order number bigger than 0. All
order numbers are internally. They are given only to service that are marked
-as favorite. For WiFi, WiMAX and Bluetooth a successful connection attempt
-makes these services automatically a favorite. For Ethernet the plugging
-of a cable makes it a favorite. Disconnecting from a network doesn't remove
-the favorite setting. It is a manual operation and is equal to users pressing
+as favorite. For WiFi and Bluetooth a successful connection attempt makes
+these services automatically a favorite. For Ethernet the plugging of a cable
+makes it a favorite. Disconnecting from a network doesn't remove the favorite
+setting. It is a manual operation and is equal to users pressing
delete/remove button.
+---------------------------------------+
| |
Ethernet is special here since the unplugging of the network cable will
-remove the favorite selection.
+remove the service from the list
+---------------------------------------+
| Ethernet with cable | order=1 - favorite=yes
+---------------------------------------+
- | Ethernet without cable | order=0 - favorite=no
- +---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
This means that all services with an order > 0 have favorite=yes and all
-other have favorite=no setting. The favorite setting is exposed via a
+others have favorite=no setting. The favorite setting is exposed via a
property over the service interface. As mentioned above, the order number
is only used internally.
-Within Connection Manager many service can be connected at the same time and
+Within Connection Manager many services can be connected at the same time and
also have an IP assignment. However only one can have the default route. The
-service with the the default route will always be sorted at the top of the
+service with the default route will always be sorted at the top of the
list.
+---------------------------------------+
+---------------------------------------+
| |
-Another possible user interaction would be to unplug the Ethernet cable and
-in this case the favorite setting will be removed and the service falls back
-down in the list.
+Another possible user interaction would be to disconnect the Ethernet service
+and in this case the service falls back down in the list.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=yes
+---------------------------------------+
- | Ethernet | order=0
+ | Ethernet | order=1 - connected=no
+---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
+---------------------------------------+
| |
-Unplugging the Ethernet cable will remove the favorite setting, but due to
-the basic ordering of services it will be at the top of the services with an
-order number of 0 (directly after all favorite services).
+Unplugging the Ethernet cable will remove the Ethernet service.
+---------------------------------------+
| My WiFi AP (strength 80, rsn) | order=1 - connected=no
+---------------------------------------+
- | Ethernet | order=0 - connected=no
- +---------------------------------------+
| Guest (strength 90, none) | order=0
+---------------------------------------+
| |
The service interface is not meant for basic device configuration task. So
switching a device on and off (via RFKILL for example) should be done via
-the device interface.
+the technology interface. See "Technology interfaces" chapter in this document.
Due to limited screen size of small devices and the big amount of WiFi
access points that are deployed right now it might be sensible to not show
will be converted into printable form. Unprintable characters are replaced
with spaces.
-For WiMAX networks the provide name like Clear or X-OHM will be used. This
-name either comes directly from the networks itself or from a provisioning
-database of the WiMAX service.
+In addition to WiFi naming, WiFi networks are subject to a grouping policy
+performed around SSID and security type. This means that one service will be
+seen for N WiFi networks providing the same SSID and the same security method.
+For instance, if 5 APs are servicing an SSID called "TEST" with WPA2
+authentication and 3 APs are servicing the same SSID with open authentication
+method, the user will see only two services listed with the name "TEST"
+differentiated by their security type, which are "psk" and "none". Such
+policy is also applied to hidden networks, where hidden services will have an
+empty name and will be differentiated by the security type. The user has then
+to select the one with the right security and the Agent API will request any
+required information such as the SSID for the network (See "Application
+basics" below).
For Bluetooth the device alias is used. The alias is different since it
can be overwritten by the user via the Bluetooth service. The identification
With the "configuration" state the service indicates that it is trying
to retrieve/configure IP settings.
-Some service might require special authentication procedure like a web based
-confirmation. The "login" should be used for this in the future. Currently
-this is not implemented.
-
The "ready" state signals a successful connected device. This doesn't mean
it has the default route, but basic IP operations will succeed.
+---------------+
| idle |<-------------------------------+
- +---------------+ |
- | |
+ +---------------+ A |
+ | clear error | |
| +-------------+ |
+----------------------| failure | |
| service.Connect() +-------------+ |
| success |
V |
+---------------+ |
- | ready |<----------------+ |
+ | ready | |
+ +---------------+ |
+ | |
+ | success |
+ | |
+ V |
+ +---------------+ |
+ | online |<----------------+ |
+---------------+ | |
| | |
| service.Disconnect() | |
| |
+------------------------------------------+
-The different states should no be used by the user interface to trigger
+The different states should not be used by the user interface to trigger
advanced actions. The state transitions are provided for the sole purpose
to give the user feedback on what is currently going on. Especially in
cases where networks are flaky or DHCP servers take a long time these
information are helpful for the user.
+Some services might require special authentication procedure like a web
+based confirmation. The LoginRequired property should be used to check
+for this.
+
Application basics
==================
bus = dbus.SystemBus()
- manager = dbus.Interface(bus.get_object("org.moblin.connman", "/"),
- "org.moblin.connman.Manager")
+ manager = dbus.Interface(bus.get_object("net.connman", "/"),
+ "net.connman.Manager")
properties = manager.GetProperties()
The services are represented as a list of object paths. Every of these object
paths contains a service interface. A service is a global collection for
-Ethernet devices, WiFi networks, Bluetooth services, WiMAX providers etc. and
-all these different types are treated equally.
+Ethernet devices, WiFi networks, Bluetooth services etc. and all these
+different types are treated equally.
Every local Ethernet card will show up as exactly one service. WiFi networks
will be grouped by SSID, mode and security setting. Bluetooth PAN and DUN
-service will show up per remote device. For WiMAX the provider name will
-be used for grouping different base stations and access providers. This
-creates a simple list that can be directly displayed to the users since these
-are the exact details users should care about.
+service will show up per remote device. This creates a simple list that can
+be directly displayed to the users since these are the exact details users
+should care about.
properties = manager.GetProperties()
for path in properties["Services"]:
- service = dbus.Interface(bus.get_object("org.moblin.connman", path),
- "org.moblin.connman.Service")
+ service = dbus.Interface(bus.get_object("net.connman", path),
+ "net.connman.Service")
service_properties = service.GetProperties()
service.Connect() or service.Disconnect()
-It is possible to connect multiple service if the underlying technology
+It is possible to connect multiple services if the underlying technology
allows it. For example it would be possible to connect to a WiFi network
and a Bluetooth service at the same time. Trying to connect to a second WiFi
network with the same WiFi hardware would result in an automatic disconnect
can fail for one reason or another. Application should be able to handle
such errors and will also be notified of changes via signals.
-In future versions Connection Manager will interact with an agent to confirm
-certain transaction with the user. This functionality is currently not
-implemented.
+Connection Manager will interact with an agent via the Agent API to confirm
+certain transactions with the user. If Connection Manager needs extra
+information, it will ask the user for exactly the information it requires,
+i.e. passphrase, network's name (for hidden WiFi networks) and more depending
+on the use case (e.g. WPS, EAP). Therefore an application environment using
+Connection Manager should implement one dedicated Connection Manager agent
+according to the Agent API in order to interact with the user. Please see
+agent-api.txt for implementation details.
To monitor the current status of a service the state property can be used. It
gives detailed information about the current progress.
print properties["State"]
-All state changes are also send via the PropertyChanged signal on the
+All state changes are also sent via the PropertyChanged signal on the
service interface. This allows asynchronous monitoring without having to poll
Connection Manager for changes.
+
+
+Technology interfaces
+=====================
+
+When ConnMan is started first time, all technologies except ethernet are
+powered off by default. The reason is that the user needs to decide which
+technologies are relevant to him and what bearers the user wants to use.
+User can use the Technology Powered property to turn on or off a given
+technology. See doc/technology-api.txt document for details.
+
+User can activate offline (flight) mode via Manager OfflineMode property.
+While in offline mode, all the technologies including ethernet are
+powered off. During the offline mode, the user can temporarily activate
+individual technologies by using the Technology Powered property or by
+using the rfkill command or Fn-Fx key combination found in some laptops.
+
+If the host supports rfkill switch, then all the radios can be turned off
+by the kernel when the switch is activated. ConnMan will notice this and
+remove corresponding technologies from D-Bus. Technologies cannot be
+activated while rfkill switch is turned on. When rfkill switch is turned
+off (radios are activated), then ConnMan restores the original Powered
+status for each activated technology.
+
+User can use the rfkill command from command line or indirectly via
+some UI component to activate/deactivate individual radios found in
+the host. ConnMan will listen these rfkill events and set the Powered
+property accordingly. ConnMan will not save the rfkill status it has
+received. This means that after restarting ConnMan, the original and
+saved technology status is used when deciding which technologies should
+be powered. If the user uses the Technology D-Bus API to set the Powered
+property, then that information is saved and used when ConnMan is restarted.
projects / platform / upstream / connman.git / blobdiff