# nymea-networkmanager This daemon allows to set up the wireless network using a bluetooth LE connection. The daemon will automatically start a bluetooth low energy server if the system is currently not connected to any network. Once the system is connected, the daemon will shutdown the bluetooth server. # Config file nymea-networkmanager will search for a config file in the following locations (in this order): ~/.config/nymea/nymea-networkmanager.conf /etc/nymea/nymea-networkmanager.conf If such a config file is found, it reads values from there. There is a example config in this repository and it will be installed to /etc/nymea-networkmanager.conf with the dpkg package. Note: Command line parameters will have higher priority than entries in the configuration file. # Command line parameters $ nymea-network-manager --help Usage:nymea-networkmanager [options] This daemon allows to configure a wifi network using a bluetooth low energy connection. Copyright © 2018 Simon Stürz Options: -h, --help Displays this help. -v, --version Displays version information. -d, --debug Enable more debug output. -a, --advertise-name The name of the bluetooth server. Default "nymea". -p, --platform-name The name of the platform this daemon is running. Default "nymea-box". -t, --timeout The timeout of the bluetooth server. Minimum value is 10. Default "60". -m, --mode Run the daemon in a specific mode. Default "offline". - offline: this mode starts the bluetooth server once the device is offline and not connected to any LAN network. - always: this mode enables the bluetooth server as long the application is running. - start: this mode starts the bluetooth server for 3 minutes on start and shuts down after a connection. # Bluetooth GATT profile ------------------------------------------- In order to connect to nymea-networkmanager using bluetooth low energy, once has to perform a bluetooth discovery, filter for all low energy devices and connect to the device with the name `nymea`. The remote address type for connecting to `nymea-networkmanager` is `public`. ## Behaviour ## Notifications In order to enable/disable the notification for a characteristic with the `notify` flag, a client has to write the value `0x0100` for enabling and `0x0000` for disabling to the descriptor `0x2902` of the corresponding characteristic. ## Services: ### Overview | Name | Service UUID | Description | ------------------ | -------------------------------------- | ---------------------------------------------------- | Generic Access | `00001800-0000-1000-8000-00805f9b34fb` | The service contains generic information about the device | Generic Attribute | `00001801-0000-1000-8000-00805f9b34fb` | Default service for Bluetooth LE GATT devices | Device information | `0000180a-0000-1000-8000-00805f9b34fb` | The service contains information about the device and manufacturer | Wireless service | `e081fec0-f757-4449-b9c9-bfa83133f7fc` | The wifi service for managing the wireless network | Network service | `ef6d6610-b8af-49e0-9eca-ab343513641c` | The network service for managing the network > **S** = Service; **C** = Characteristic; **D** = Descriptor > **W** = Write; **R** = Read; **N** = Notify #### **S**: Generic Access > Default service for Bluetooth LE GATT devices. More information can be found [here](https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.service.generic_access.xml). #### **S**: Generic Attribute > Default service for Bluetooth LE GATT devices. More information can be found [here](https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.service.generic_attribute.xml). #### **S**: Device Information > Default service for Bluetooth LE GATT devices. More information can be found [here](https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.service.device_information.xml). #### **S**: Wireless service `e081fec0-f757-4449-b9c9-bfa83133f7fc` The *Wireless Service* allows a client to configure and monitor a wireless network connection. The connection can be controlled with the *Wireless commander* characteristic. Each command sent will generate a respone on the *Comander response* characteristic containing the error code for the command. The *Wireless connection status* characteristic informs the client about the current connection status of the wireless device. **Characteristic overview** | Name | Characterisitc UUID | Flag | Description | -------------------------- | -------------------------------------- | ------ | ------------------------------------------------------- | Wireless commander | `e081fec1-f757-4449-b9c9-bfa83133f7fc` | **W** | Controll what the wifi manager should do. | Commander response | `e081fec2-f757-4449-b9c9-bfa83133f7fc` | **N** | This characteristic will be used to inform about the command result (error reporting). | Wireless connection status | `e081fec3-f757-4449-b9c9-bfa83133f7fc` | **RN** | Informs about the current wireless connection status. **Characteristic details** - **C**: *Wireless commander* (W) `e081fec1-f757-4449-b9c9-bfa83133f7fc` - *Description*: Controll characteristic for the wireless manager. Each command sent to this characteristic will create a response report on the *Commander response* characterisitc. - *Range*: [0-20] Byte, UTF-8, JSON - *Possible values*: In following example you can find the basic structure of a command and a response. The command can be sent to this *Wireless commander* characteristic, the response will be notified on the *Commander response* characteristic. The JSON object containing the command map has to be formated compact and must end with the '\n' character. If a data package is longer than the allowed 20 Bytes, the data must be splitted into 20 Byte packages and sent in the correct order. The end of a JSON data stream will be recongnized, once the '\n' character will be found at the end of a package. The *Commander response* characteristic uses the same mechanism. - Request { "c": 0, // Integer: Command: describing the method called "p": { } // The parameters of the method. If the method does not have any parameters you can skip this. } - Response { "c": 0, // Integer: Command: describing the method called "r": 0, // Integer: Response error code. See list of error codes. "p": Object or Array // Object or Array. This value is optional and depends on the requested command. } - List of response error code: | Value | Name | Description | ------ | -------------------------- | ---------------------------------------------------- | `0` | Success | The command has been executed successfully. | `1` | InvalidCommand | The commander received an invalid command. | `2` | InvalidParameter | The commander received an invalid parameter. | `3` | NetworkManagerNotAvailable | Network manager is currently not available (`network-manager` daemon or dbus not running). | `4` | WirelessNotAvailable | Wireless currently not available. There is no wireless adapter in the system. | `5` | NetworkingDisabled | Networking is not enabled. One can enable it in the *Network service*. | `6` | WirelessDisabled | Wireless networking is not enabled. One can enable it in the *Network service*. | `7` | Unknown | An unknown error happend. #### Methods | Value | Name | Description | ------ | -------------- | ---------------------------------------------------- | `0` | GetNetworks | Get the current wifi network list on the "Wireless data stream". | `1` | Connect | Connect to the network with the given ssid and password in **C** `e081fec4` and **C** `e081fec5`. If the network is open, set the password characteristic to an empty string. | `2` | ConnectHidden | Connect to the hidden network using the given ssid and password in **C** `e081fec4` and **C** `e081fec5`. | `3` | Disconnect | Disconnect from current wireless network. | `4` | Scan | Perform a wireless accesspoint scan. | `5` | GetConnection | Get the current connection information on the "Wireless data stream" ##### - GetNetworks (0) - Request { "c": 0 // Command: GetNetworks } - Response { "c": 0, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. "p": [ { "e": "My network", // String: ESSID: the name of the wifi network "m": "AA:BB:CC:DD:EE", // String: The MAC address of the wifi access point "s": 86, // Integer: Signal strength [0-100] % "p": 0 // Integer: Protected [0,1]; 0 - open, 1 - protected } ] } ##### - Connect (1) - Request { "c": 1, // Command: Connect "p": { "e": "Wifi SSID" // The SSID of the wifi access point you want to connect to "p": "Wifi password" // The password of the access point you want to connect to } } - Response { "c": 1, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. } ##### - ConnectHidden (2) - Request { "c": 2, // Command: ConnectHidden "p": { "e": "Wifi SSID" // The SSID of the wifi access point you want to connect to "p": "Wifi password" // The password of the access point you want to connect to } } - Response { "c": 2, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. } ##### - Disconnect (3) - Request { "c": 3 // Command: Disconnect } - Response { "c": 3, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. } ##### - Scan (4) - Request { "c": 4 // Command: Scan } - Response { "c": 4, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. } ##### - GetConnection (5) - Request { "c": 5 // Command: GetConnection } - Response { "c": 5, // Integer: Command: describing the method called "r": 0 // Integer: Response error code. See list of response error codes. "p": { "e": "My network", // String: ESSID: the name of the current wifi network "m": "AA:BB:CC:DD:EE", // String: The MAC address of the current wifi access point "s": 86, // Integer: Signal strength [0-100] % "p": 0, // Integer: Protected [0,1]; 0 - open, 1 - protected "i": "192.168.0.12" // String: The IP address of the current wifi connection } } - **C**: *Commander response* (N) `e081fec2-f757-4449-b9c9-bfa83133f7fc` - *Description*: Sends a JSON object in 20 Byte packages. The data stream is finished once the \n charater received at the end of a package. - *Range*: [0-20] Byte, UTF-8, JSON - *Possible values*: See "methods - response" for more details The JSON object containing the response map has to be formated compact and must end with the '\n' character. If a data package is longer than the allowed 20 Bytes, the data must be splitted into 20 Byte packages and sent in the correct order. The end of a JSON data stream will be recongnized, once the '\n' character will be found at the end of a package. The *Commander* characteristic uses the same mechanism. - **C**: *Wireless connection status* (RN) `e081fec3-f757-4449-b9c9-bfa83133f7fc` - *Description*: This characteristic represents the current state of the wireless adapter. - *Range*: 1 Byte, Hex value - *Possible values*: | Value | Name | Description | ------ | ------------ | ---------------------------------------------------- | `0x00` | Unknown | The device state is unknown. | `0x01` | Unmanaged | The device is recognized, but not managed by NetworkManager. | `0x02` | Unavailable | The device is managed by NetworkManager, but is not available for use (i.e. Wireless switched off, missing firmware). | `0x03` | Disconnected | The device can be activated, but is currently idle and not connected to a network. | `0x04` | Prepare | The device is preparing the connection to the network. | `0x05` | Config | The device is connecting to the requested network (Associating with the WiFi accesspoint). | `0x06` | NeedAuth | The device requires more information to continue connecting to the requested network. | `0x07` | IpConfig | The device is requesting IPv4 and/or IPv6 addresses and routing information from the network. | `0x08` | IpCheck | The device is checking whether further action is required for the requested network connection. This may include checking whether only local network access is available, whether a captive portal is blocking access to the Internet. | `0x09` | Secondaries | The device is waiting for a secondary connection (like a VPN) which must activated before the device can be activated. | `0x0A` | Activated | The device has a network connection, either local or global. | `0x0B` | Deactivating | A disconnection from the current network connection was requested, and the device is cleaning up resources used for that connection. The network connection may still be valid. | `0x0C` | Failed | The device failed to connect to the requested network and is cleaning up the connection request. #### **S**: Network service `ef6d6610-b8af-49e0-9eca-ab343513641c` This service allows to monitor and configure the `network-manager` daemon running on the system. **Characteristic overview** | Name | Characteristic UUID | Flag | Description | ----------------------------- | -------------------------------------- | ------ | -------------------------------------------------------- | Network status | `ef6d6611-b8af-49e0-9eca-ab343513641c` | **RN** | Represents the current network manager state. | Network commander | `ef6d6612-b8af-49e0-9eca-ab343513641c` | **W** | Controll what the network manager should do. | Commander response | `ef6d6613-b8af-49e0-9eca-ab343513641c` | **N** | This characteristic will be used to inform about the command result (error reporting). | Networking enabled | `ef6d6614-b8af-49e0-9eca-ab343513641c` | **RN** | This characteristic indicates if the networking in the `network-manager` is enabled. | Wireless enabled | `ef6d6615-b8af-49e0-9eca-ab343513641c` | **RN** | This characteristic indicates if the wireless networking in the `network-manager` is enabled. **Characteristic details** - **C**: *Network status* (RN) `ef6d6611-b8af-49e0-9eca-ab343513641c` - *Description*: Represents the current network manager state. - *Range*: 1 Byte, Hex value - *Possible values*: | Value | Name | Description | ------ | --------------- | ---------------------------------------------------- | `0x00` | Unknown | The networking state is unknown. | `0x01` | Asleep | Networking is not enabled. | `0x02` | Disconnected | There is no active network connection. | `0x03` | Disconnecting | Network connections are being cleaned up. | `0x04` | Connecting | A network connection is being started. | `0x05` | Local | There is only local IPv4 and/or IPv6 connectivity | `0x06` | ConnectedSite | There is only site-wide IPv4 and/or IPv6 connectivity | `0x07` | ConnectedGlobal | There is global IPv4 and/or IPv6 Internet connectivity - **C**: *Network commander* (W) `ef6d6612-b8af-49e0-9eca-ab343513641c` - *Description*: Controll what the network manager should do. - *Range*: 1 Byte, Hex value - *Possible values*: | Value | Name | Description | ------ | ------------------- | ---------------------------------------------------- | `0x00` | EnableNetworking | Enable networking on the system. | `0x01` | DisableNetworking | Disable networking on the system. | `0x02` | EnableWireless | Enable wireless networking on the system. | `0x03` | DisableWireless | Disable wireless networking on the system. - **C**: *Commander response* (N) `ef6d6613-b8af-49e0-9eca-ab343513641c` - *Description*: This characteristic will be used to inform about the command result (error reporting). - *Range*: 1 Byte, Hex value - *Possible values*: | Value | Name | Description | ------ | -------------------------- | ---------------------------------------------------- | `0x00` | Success | The command has been executed successfully. | `0x01` | InvalidValue | The commander received an invalid command. | `0x02` | NetworkManagerNotAvailable | Network manager is currently not available (`network-manager` daemon or dbus not running). | `0x03` | WirelessNotAvailable | Wireless currently not available. There is no wireless adapter in the system. | `0x04` | Unknown | An unknown error happend. - **C**: *Networking enabled* (RN) `ef6d6614-b8af-49e0-9eca-ab343513641c` - *Description*: This characteristic indicates if the networking in the `network-manager` is enabled. - *Range*: 1 Byte, Hex value - *Possible values*: - `0x00` : Disabled - `0x01` : Enabled - **C**: *Wireless enabled* (RN) `ef6d6615-b8af-49e0-9eca-ab343513641c` - *Description*: This characteristic indicates if the wireless networking in the `network-manager` is enabled. - *Range*: 1 Byte, Hex value - *Possible values*: - `0x00` : Disabled - `0x01` : Enabled