ALConnectionManager API

Overview - API | NetworkInfo | NetworkInfo-IPInfo


ALConnectionManager provides methods to manage the network connectivity. It contains commands allowing you to configure or connect a network, but also to get the network properties or to create a network.

Event list

std::string ALConnectionManagerProxy::state()

Returns the global state of the network connectivity. Possible values are:

  • “online” if an Internet connection is available.
  • “ready” this state means that at least one service is successfully connected.
  • “offline” this state means there is no network connection.
# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy

NAO_IP = "127.0.0.1"

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

print "network state: " + alconnman.state()
Returns:The global state of the connection manager.
void ALConnectionManagerProxy::scan()

Scan for neighbor services on all available technologies. This is useful to refresh the list of services, which disappears after a while(specially for WiFi services).

AL::ALValue ALConnectionManagerProxy::services()

Returns the list of all services with their properties. It might be useful to call the ALConnectionManagerProxy::scan() method before.

Returns:An array of NetworkInfo contained in an ALValue. ALValue NetworkInfo.

Listing the available services.

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi       import ALProxy

NAO_IP = "127.0.0.1"

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

#Scanning is required to update the services list
alconnman.scan()
services = alconnman.services()

for service in services:
    network = dict(service)
    if network["Name"] == "":
        print "{hidden} " + network["ServiceId"]
    else:
        print network["Name"] + " " + network["ServiceId"]
AL::ALValue ALConnectionManagerProxy::technologies()

Returns an array of string representing the available technologies, possible values are:

  • “ethernet”
  • “wifi”
  • “bluetooth”
Returns:A list of available technologies.

Listing the available technologies

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy

NAO_IP = "127.0.0.1"

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

technologies = alconnman.technologies()

if len(technologies) >0:
    print "available technology: "

    for technology in technologies:
        print "\t" + technology
AL::ALValue ALConnectionManagerProxy::service(const std::string& serviceId)

Returns the properties of a given service identifier, the NetworkInfo is represented as ALValue: ALValue representation of NetworkInfo.

Parameters:
  • serviceId – The identifier of the service to get the properties.
Returns:

the properties of the given service identifier.

Throw :

ALError when the service is not available.

Getting the properties of a service.

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  service = alconnman.service(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)

service = dict(service)
print "Network Service: " + sys.argv[1]
for key, value in service.iteritems():
    print "\t" + key + ": " + str(value)
void ALConnectionManagerProxy::connect(const std::string& serviceId)

Connects to a network service.

Parameters:
  • serviceId – The identifier for the service to connect.
Throws :

ALError when the service not available.

Note

If some information are required to connect to this service, like a passphrase or the service name (for hidden services) an event will be raised.

Connecting to a service.

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
    alconnman.connect(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)
void ALConnectionManagerProxy::disconnect(const std::string& serviceId)

Disconnects from the service.

Parameters:
  • serviceId – The identifier of the service to disconnect.
Throw :

ALError when the service is not available.

Disconnecting a service

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  alconnman.disconnect(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)
void ALConnectionManagerProxy::forget(const std::string& serviceId)

Removes a favorite service. Requests the given serviceId to forget association information. This will set the favorite and auto-connect boolean to false.

Parameters:
  • serviceId – The identifier of the network to forget.
Throw :

ALError when the service is not available.

Removing a preferred service.

# -*- encoding: UTF-8 -*- 
#!/usr/bin/env python
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  service = alconnman.forget(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)
void ALConnectionManagerProxy::setServiceConfiguration(const AL::ALValue& configuration)

Requests to apply static service configuration. The following properties are available for static settings.

  • Autoconnect
  • Domains
  • Nameservers
  • IPv4
  • IPv6 Experimental
Parameters:
  • serviceId – A NetworkInfo contained in a ALValue to apply as configuration.
Throw :

ALError when the service is not available, when the configuration is not valid or when the service doesn’t requires an input.

See also

NetworkInfo

void ALConnectionManagerProxy::setServiceInput(const AL::ALValue& input)

Provides the connection manager module with the inputs required to finish a pending connection. This method must be called when receiving the NetworkServiceInputRequired event.

Parameters:
  • input – An Input object contained in an ALValue.
Throw :

ALError when the service is not available, or when the input is not valid.

void ALConnectionManagerProxy::scan(const std::string& technology)

Scans for reachable services.

Parameters:
  • technology – The type of technology to scan.
void ALConnectionManagerProxy::enableTethering(const std::string& technology)

Creates a Network Access Point on a given technology and share Internet connection if any. For WiFi technology you have to set the Name and the Passphrase before.

Parameters:
  • technology – The type of technology on which enabling tethering mode. Only support “bluetooth” and “wifi”
Throw :

ALError when the technology is not supported by tethering mode.

Enabling Tethering

#!/usr/bin/env python
from naoqi import ALProxy
import sys
import time

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2 and len(sys.argv) != 4:
    print sys.argv[0] + " <technology> [Name] [Passphrase]"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

technology = sys.argv[1]

if len(sys.argv) == 4:
    name = sys.argv[2]
    passphrase = sys.argv[3]
    try:
        alconnman.enableTethering(technology, name, passphrase)
    except Exception as e:
        print e
        sys.exit(1)
else:
    try:
        alconnman.enableTethering(technology)
        time.sleep(2)
    except Exception as e:
        print e
        sys.exit(1)

if alconnman.getTetheringEnable(technology) == True:
    print "tethering is enabled"
else:
    print "tethering is disabled"
void ALConnectionManagerProxy::enableTethering(const std::string& technology, const std::string& name, const std::string& passphrase)

Creates a WPA2 secured Network Access Point on a given technology and share Internet connection if any.

Parameters:
  • technology – The type of technology on which enabling tethering mode. Only support “wifi”
  • name – The name of the network to create.

A valid network name has a maximum length of 32 characters and a minimum of 1 characters.

Parameters:
  • passphrase – The WPA2 passphrase to connect to the created network.

A valid WPA passphrase has a maximum length of 63 characters and a minimum of 8 characters.

Throw :ALError when the technology is not supported by tethering mode.
void ALConnectionManagerProxy::disableTethering(const std::string& technology)

Disables the Tethering mode.

Parameters:
  • technology – The type of technology on which disabling tethering mode.
Throw :

ALError when the technology is not supported by tethering mode.

bool ALConnectionManagerProxy::getTetheringEnable(const std::string& technology)
Parameters:
  • technology – The type of technology.
Returns:

A boolean, true if Tethering mode is enabled false instead.

Throw :

ALError when the technology is not supported by tethering mode.

std::string ALConnectionManagerProxy::tetheringName(const std::string& technology)
Parameters:
  • technology – The type of technology. only support “wifi”
Returns:

Returns the service name used for the tethering mode.

Throw :

ALError when the technology is not supported by tethering mode.

std::string ALConnectionManagerProxy::tetheringPassphrase(const std::string& technology)
Parameters:
  • technology – The type of technology. only support “wifi”
Returns:

Returns the passphrase used for the tethering mode.

Throw :

ALError when the technology is not supported by tethering mode.

ALConnectionManagerProxy Events

Event: "NetworkStateChanged"
callback(std::string eventName, const std::string &state, std::string subscriberIdentifier)

Raised when the global connectivity state changed.

Parameters:
  • eventName (std::string) – “NetworkStateChanged”
  • state – The state of the connection manager (same value as ALConnectionManagerProxy::state() ).
  • subscriberIdentifier (std::string) –
Event: "NetworkDefaultTechnologyChanged"
callback(std::string eventName, const std::string &techology, std::string subscriberIdentifier)

Raised when default technology changed.

Parameters:
  • eventName (std::string) – “NetworkDefaultTechnologyChanged”
  • technology – The new technology used for outgoing connection.
  • subscriberIdentifier (std::string) –
Event: "NetworkServiceStateChanged"
callback(std::string eventName, AL::ALValue &serviceState, std::string subscriberIdentifier)

Raised when a service state is changed.

Parameters:
  • eventName (std::string) – “NetworkServiceStateChanged”
  • state – A pair which contains the serviceId and the state of the service.
  • subscriberIdentifier (std::string) –

The state of the service uses the same values as NetworkInfo::state().

Event: "NetworkServiceRemoved"
callback(std::string eventName, const std::string &serviceId, std::string subscriberIdentifier)

Raised when a service is removed from the service list.

Parameters:
  • eventName (std::string) – “NetworkServiceRemoved”
  • serviceId – the service identifier of the removed service.
  • subscriberIdentifier (std::string) –
Event: "NetworkServiceAdded"
callback(std::string eventName, const std::string &serviceId, std::string subscriberIdentifier)

Raised when a service is added to the service list.

Parameters:
  • eventName (std::string) – “NetworkServiceAdded”
  • serviceId – the service identifier of the added service.
  • subscriberIdentifier (std::string) –
Event: "NetworkServiceInputRequired"
callback(std::string eventName, const AL::ALValue &inputRequest, std::string subscriberIdentifier)

Raised when a connection to a service requires input information to succeed.

Parameters:
  • eventName (std::string) – “NetworkServiceInputRequired”
  • inputRequest – the requested inputs stored in a ALValue see ALValue Input Request
  • subscriberIdentifier (std::string) –

When this event is reveived you have to provide the required input using ALConnectionManagerProxy::setServiceInput().

Some examples of possible reply are available bellow. ALValue Input Reply

Event: "NetworkTechnologyAdded"
callback(std::string eventName, const std::string &technology, std::string subscriberIdentifier)

Raised when a new technology is available.

Parameters:
Event: "NetworkTechnologyRemoved"
callback(std::string eventName, const std::string &technology, std::string subscriberIdentifier)

Raised when a new technology is no longer available.

Parameters:
  • eventName (std::string) – “NetworkTechnologyRemoved”
  • technology – the name of the technology (same values as ALConnectionManagerProxy::technologies()).
  • subscriberIdentifier (std::string) –

ALValue Input Request

This ALValue notifies the needed inputs to succeed in a network connection.

The Input Request is an array of n-pair (key, value).

All the requests contain the key “Network”, the identifier for the network service.

The different keys could be:

  • “Passphrase” for a WEP or WPA/WPA2 passphrase
  • “WPS” for a Wireless Protected Setup enabled Access Point
  • “Name” for the name of a hidden network.
  • “Identity” for a WPA Enterprise Network. Experimental
  • “Username” for a WISPr enabled hotspot. Experimental
  • “Password” for the user password for WPA enterprise or WiSPr Access Point. Experimental
Key Value type Value content
“ServiceId” String The service identifier
“Passphrase” ALValue ALValue Input Details
“WPS” ALValue ALValue Input Details
“Name” ALValue ALValue Input Details
“Identity” ALValue ALValue Input Details
“Password” ALValue ALValue Input Details
“Username” ALValue ALValue Input Details

ALValue Input Details

The Input Details is an array of n-pair (key, value).

A network service may support several authentication methods, in this case it will ask you which method you want to use before requesting further inputs depending on the chosen authentication method. For example most of the recent Access Point support the WPA2 and the WPS as alternative method for the authentication.

The possible keys for the Input Details are:

Key Value type Value content
“Requirement” string

which represents the requirement for the input

Possible values are “Mandatory” or “alternate”

“Alternates” array of string representing the alternatives method.
“Type” string

The type of the requested input.

This can be:

  • “psk” for a WPA/WPA2 passphrase,
  • “wpspin” for a WPS pin code,
  • “string” for a non secret text, or
  • “passphrase” or a WPA Enterprise passphrase.

ALValue Input Reply

The Input Reply is an array of n-pair (key, value).

All the replies to request input must contain the key “ServiceId” with the network service identifier as value.

The Input Reply must also contain all the mandatory fields requested by the event NetworkServiceInputRequired().

Examples:

  • ALValue reply for a WPA/WPA2 Enabled Access Point.

    Key

    Value content

    “ServiceId”

    string

    “Passphrase”

    “Mysecretpassphrase”

  • ALValue reply for a WPA/WPA2 Enabled Access Point with hidden SSID.

    Key

    Value content

    “ServiceId”

    string

    “Passphrase”

    “Mysecretpassphrase”

    “Name”

    “MyHiddenSSID”

  • ALValue reply for a WPS Enabled Access Point with hidden SSID, using the WPS push button method.

    Key

    Value content

    “ServiceId”

    string

    “WPS”

    “’” (reply an empty string to select push button or give a PIN code to select PIN code method)

    “Name”

    “MyHiddenSSID”