*********************************
+Service basics
+==============
+
+Inside Connection Manager there exists one advanced interface to allow the
+user interface an easy access to networking details and user chosen
+preferences. This is the service list and interface.
+
+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).
+
+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
+need to be done via Connection Manager and it is then responsible to update
+the order of services in this list.
+
+ +---------------------------------------+
+ | Ethernet |
+ +---------------------------------------+
+ | Bluetooth phone |
+ +---------------------------------------+
+ | Guest (strength 90, none) |
+ +---------------------------------------+
+ | 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 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)
+
+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
+manually they will not be showing in this list.
+
+Since every Bluetooth device has to be configured/paired first, the user
+already made a choice here that these are important. Connection Manager will
+only show devices with PAN or DUN profile support. While Bluetooth devices
+do have a signal strength, it is mostly unknown since background scanning
+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 then 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 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.
+
+
+Service order
+=============
+
+All unused services will have the internal order number of 0 and then will
+be sorted according to the rules above. For Bluetooth the user already made
+the decision to setup their device and by that means select it. However
+until the first connection attempt it might have been setup for total
+different reason (like audio usage) and thus it still counts as unused from
+a networking point of view.
+
+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
+delete/remove button.
+
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | order=1 - favorite=yes
+ +---------------------------------------+
+ | Ethernet | order=0
+ +---------------------------------------+
+ | Guest (strength 90, none) | order=0
+ +---------------------------------------+
+ | |
+
+Ethernet is special here since the unplugging of the network cable will
+remove the favorite selection.
+
+ +---------------------------------------+
+ | 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
+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 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 default route will always be sorted at the top of the
+list.
+
+ +---------------------------------------+
+ | Ethernet | order=2 - connected=yes
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | order=1 - connected=yes
+ +---------------------------------------+
+ | Guest (strength 90, none) | order=0
+ +---------------------------------------+
+ | |
+
+To change the default connection to your access point, the user needs to
+manually drag the access point service to the top of the list. Connection
+Manager will not take down default routes if there is no reason to do so.
+A working connection is considered top priority.
+
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | order=2 - connected=yes
+ +---------------------------------------+
+ | Ethernet | order=1 - connected=yes
+ +---------------------------------------+
+ | Guest (strength 90, none) | order=0
+ +---------------------------------------+
+ | |
+
+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.
+
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | order=1 - connected=yes
+ +---------------------------------------+
+ | Ethernet | order=0
+ +---------------------------------------+
+ | Guest (strength 90, none) | order=0
+ +---------------------------------------+
+ | |
+
+If the service on the top of the list changes the default route will be
+automatically adjusted as needed. The user can trigger this by disconnecting
+from a network, if the network becomes unavailable (out of range) or if the
+cable gets unplugged.
+
+As described above, the pure case of disconnecting from a network will not
+remove the favorite setting. So previously selected networks are still present
+and are sorted above all others.
+
+ +---------------------------------------+
+ | Ethernet | order=2 - connected=yes
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | 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).
+
+ +---------------------------------------+
+ | My WiFi AP (strength 80, rsn) | order=1 - connected=no
+ +---------------------------------------+
+ | Ethernet | order=0 - connected=no
+ +---------------------------------------+
+ | Guest (strength 90, none) | order=0
+ +---------------------------------------+
+ | |
+
+
+Service tweaks
+==============
+
+The interfaces of Connection Manager will always export all services that are
+currently known. The Ethernet devices with no cable plugged are actually not
+included in this list. They will only show up once a carrier is detected.
+
+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.
+
+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
+certain WiFi networks in the user interface.
+
+The choice to hide a WiFi network from the user interface should be purely
+done by the signal strength. The optimal cut-off value here still has to be
+determined, but in the end that is a user interface policy.
+
+
+Service naming
+==============
+
+Every service will have a name property that allows the user interface to
+display them directly. All names will be already converted into UTF-8. It
+derives from the netork details.
+
+In case of WiFi this will be the SSID value. The SSID is a binary array and
+will be converted into printable form. Unprintable characters are replaced
+with spaces.
+
+For WiMAX networks the provider name like Clear or X-OHM will be used. This
+name either comes directly from the network itself or from a provisioning
+database of the WiMAX service.
+
+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
+is still done based on its address, but the display name might change. In
+most cases the alias is equal to the Bluetooth remote friendly name.
+
+For Ethernet device no name will be provided. The type property will indicate
+that this service is Ethernet and then it is up to the user interface to
+provide a proper localized name for it.
+
+
+Service states
+==============
+
+Every service can have multiple states that indicate what is currently
+going on with it. The choice to have multiple states instead of a simple
+connected yes/no value comes from the fact that it is important to let the
+user interface name if a service is in process of connecting/disconnecting.
+
+The basic state of every service is "idle". This means that this service
+is not in use at all at the moment. It also is not attempting to connect
+or do anything else.
+
+The "association" state indicates that this service tries to establish a
+low-level connection to the network. For example associating/connecting
+with a WiFi access point.
+
+With the "configuration" state the service indicates that it is trying
+to retrieve/configure IP settings.
+
+The "ready" state signals a successful connected device. This doesn't mean
+it has the default route, but basic IP operations will succeed.
+
+With the "disconnect" state a service indicates that it is going to terminate
+the current connection and will return to the "idle" state.
+
+In addition a "failure" state indicates a wrong behavior. It is similar to
+the "idle" state since the service is not connected.
+
+ +---------------+
+ | idle |<-------------------------------+
+ +---------------+ |
+ | |
+ | +-------------+ |
+ +----------------------| failure | |
+ | service.Connect() +-------------+ |
+ V A |
+ +---------------+ | |
+ | association |-----------------+ |
+ +---------------+ error | |
+ | | |
+ | success | |
+ V | |
+ +---------------+ | |
+ | configuration |-----------------+ |
+ +---------------+ error |
+ | |
+ | success |
+ V |
+ +---------------+ |
+ | ready | |
+ +---------------+ |
+ | |
+ | success |
+ | |
+ V |
+ +---------------+ |
+ | online |<----------------+ |
+ +---------------+ | |
+ | | |
+ | service.Disconnect() | |
+ V | |
+ +---------------+ | |
+ | disconnect |-----------------+ |
+ +---------------+ error |
+ | |
+ +------------------------------------------+
+
+The different states should no 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()
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
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
+certain transactions with the user. This functionality is currently not
implemented.
To monitor the current status of a service the state property can be used. It
print properties["State"]
-All state changes are also send via the PropertyChanged signal on the
-service interface. This allows asynchronous monitoring with having to poll
+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.
projects / framework / connectivity / connman.git / blobdiff