MMB Wireless Bridge Commissioning Daemon

Owned by Doug Alguire (Deactivated)
Last updated: Jun 10, 2021 by Philip Emsley (Unlicensed)
11 min read

Description

The MMB Wireless Bridge Commissioning Daemon implements a RESTful API for commissioning the device onto on premises Wi-Fi networks, and for custom application provisioning ( device individual IDs, Tokens, credentials, resource urls, etc ). The customer is able to specify a configuration file 'white list' so that only the files they specify are allowed to be uploaded via the API. On startup the daemon will start the Gateway in uAP mode, broadcasting with the SSID 'Tripoli_<Gateway ethernet mac address>'. Once connected, the API documented below ( with sample scripts in python ) can be exercised. During first touch the web GUI can be used to connect the Gateway to a local Wi-Fi network.

  • The bridge commissioning part of the service allows the user to provision and connect the device to a wireless network of their choosing
  • The executable provides a REST api to facilitate this

Location

  • The service should be running on startup, but in case it is not, the service can be found at /etc/init.d/S85wirelessbridgecommissioning and the executable can be found at /usr/sbin/wireless_bridge_commissioning.
  • The configuration, and web gui files used by the wireless_bridge_commissioning executable can be found at /opt/commissioning/

Service Usage

./wireless_commissioning -h
	wireless commissioning
	Usage:
		-h	This usage page
		-B	Run wireless commissioning in the background

Commissioning Usage

State Diagram

Bridge Commissioning Web GUI

  1. The commissioning GUI can be reached at 192.168.10.1:8080/commissioning.html
  2. Click the WIFI SCAN button at the top
    • This will cause the service to perform a scan for all 2.4 GHz networks
    • List all found networks with their associated SSID, Frequency, RSSI, and Security types
  3. Input the PASSWORD into the password field at the bottom of the form
    • Currently, there is no mechanism to support join a network with no security
  4. Press the WIFI ASSOCIATE button at the bottom of the form
    • This will cause the service to attempt to join the selected network
    • The Gateway's IP Address will be returned in green on success

RESTful API

GET /sys/scan

Scan for Wi-Fi networks

Input on /sys/scan

Channel Mask to scan.

Output on /sys/scan

200 OK

JSON array of all available and visible Wi-Fi networks where each entry contains the following: (SSID, Signal Level, Security)

We can ignore all non b/g/n and all non 2.4GHz results

JSON Format
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Wifi Scan Results",
  "description": "Result of Wifi Scan and Wifi Networks found",
  "type": "object",
  "properties": {
    "result": {
      "description": "Did the Wifi Scan succeed or fail?",
      "type": "boolean"
    },
    "found": {
      "description": "List of Wifi Networks found",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ssid": {
            "description": "Name of Wifi Network",
            "type": "string"
          },
          "security": {
            "description": "The security type of the Wifi Network",
            "type": "string"
          },
          "rssi": {
            "description": "The signal strength",
            "type": "integer"
          },
          "frequency": {
            "description": "The frequency of the Wifi Network",
            "type": "string",
            "default": "2.4",
            "enum": [
              "2.4",
              "3.6",
              "4.9",
              "5",
              "5.9"
            ]
          }
        },
        "required": [
          "ssid",
          "security",
          "rssi"
        ]
      }
    }
  },
  "required": [
    "result"
  ],
  "additionalProperties": false
}

POST /sys/associate

Connect to the Wi-Fi network pointed to by the given information

Input

JSON Format
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Wifi Scan Results",
  "description": "Connect to the specified Wifi Network",
  "type": "object",
  "properties": {
    "ssid": {
      "description": "The SSID of the Wifi Network",
      "type": "string"
    },
    "passphrase": {
      "description": "The passphrase required to connect to the Wifi Network",
      "type": "string"
    },
    "auth": {
      "description": "The Authentication type",
      "type": "string",
	  "default": "NONE",
      "enum": [
        "WLAN_AUTH_INVALID",
        "WLAN_AUTH_NONE",
        "WLAN_AUTH_WEP ",
        "WLAN_AUTH_WPA",
        "WLAN_AUTH_WPA2",
        "WLAN_AUTH_WPA2_CCKM",
        "WLAN_AUTH_WPA2_PSK",
        "WLAN_AUTH_WPA2_PSK_SHA256",
        "WLAN_AUTH_WPA_CCKM",
        "WLAN_AUTH_WPA_PSK"
      ]
    },
    "cipher": {
      "description": "The Cipher type",
      "type": "string",
	  "default": "NONE",
      "enum": [
        "WLAN_CRYPT_AES_CRYPT",
        "WLAN_CRYPT_BIP_CRYPT",
        "WLAN_CRYPT_INVALID",
        "WLAN_CRYPT_KTK_CRYPT",
        "WLAN_CRYPT_NONE",
        "WLAN_CRYPT_TKIP_CRYPT",
        "WLAN_CRYPT_WAPI_CRYPT",
        "WLAN_CRYPT_WEP_CRYPT"
      ]
    },
    "config": {
      "description": "Opaque object data to be passed",
      "type": "object"
    }
  },
  "required": [
    "ssid",
    "passphrase",
    "auth",
    "cipher"
  ],
  "additionalProperties": false
}

Output

201 Created

JSON Format
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Wifi Scan Results",
  "description": "Passing Opaque data",
  "type": "object",
  "properties": {
    "result": {
      "description": "Whether the Associate succeeded",
      "type": "boolean"
    }
  },
  "required": [
    "result"
  ],
  "additionalProperties": false
}

GET /sys/info

Input

None

Output

JSON Format
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Get System Info",
  "description": "Sotfware and Hardware information about the gateway",
  "type": "object",
  "properties": {
	"Manufacturer": {
	  "type": "string",
	  "value": "MMB Networks"
	},
	"Model_Number": {
	  "type": "string",
	  "value": "AMA01GW10"
	},
	"Kernel_Version": {
	  "type": "string"  
	},
	"RFS_Version": {
	  "type": "string"  
	},
	"MMB_Version": {
	  "type": "string"  
	},
	"ETH_MAC": {
	  "type": "string"  
	},
  }
}

POST /sys/configure

A call to this API will write the raw contents of the each individual items' "contents" the location specified by the whitelist found in the 'root' of the application directory ( /home/mmb/config_files_whitelist.conf ). If a whitelist is not found there, it will fallback to one in /etc/default/config_files_whitelist.conf.

Whitelist

{  
    "$schema":"http://json-schema.org/draft-06/schema#",
    "title":"Gateway Configuration whitelist data structure",
    "description":"Whitelist to determine which files are to be written to disk when reading the /sys/configure endpoint data",
    "type":"object",
    "properties":{  
        "whitelist":{  
            "type":"array",
            "items":{  
                "type":"object",
                "properties":{  
                    "name":{  
                        "description":"The name of the file",
                        "type":"string"
                    },
                    "path":{  
                        "description":"The location the file should be placed (No trailing slash)",
                        "type":"string"
                    },
                    "type":{  
                        "description":"The type of the file",
                        "type":"string",
                        "enum":[  
                            "json",
                            "text"
                        ]
                    },
                    "user":{  
                        "description":"Which user should own the file (default: mmb)",
                        "type":"string"
                    },
                    "group":{  
                        "description":"Which group should own the file (default: mmb)",
                        "type":"string"
                    }
                },
                "required":[  
                    "name",
                    "path",
                    "type"
                ]
            }
        }
    },
    "required":[  
        "whitelist"
    ]
}


Input

{  
    "$schema":"http://json-schema.org/draft-06/schema#",
    "title":"Gateway Configuration data structure to be written to disk",
    "description":"Passing Opaque data, along with a specific API version number for future use",
    "type":"object",
    "properties":{  
        "version":{  
            "type":"number"
        },
        "config_data":{  
            "type":"array",
            "items":{  
                "type":"object",
                "properties":{  
                    "name":{  
                        "type":"string"
                    },
                    "contents":{  
                        "type":[  
                            "string",
                            "object"
                        ]
                    }
                },
                "required":[  
                    "name",
                    "contents"
                ]
            }
        }
    },
    "required":[  
        "version",
        "config_data"
    ]
}

Output

Commissioning result

Client side customizing and branding

The client side Javascript and CSS files are available on the Gateway in /opt/commissioning/gui/

Python Exercise Scripts

api_test_sys_associate.py

api_test_sys_configure.py

api_test_sys_scan.py

api_test_sys_info.py


Corporate Branding

  • For changes to corporate branding, such as logo inserts onto pages, the relevant files can be found in /opt/commissioning/gui/
  • For all other changes, such as custom api call endpoints or cloud commissioning support, please contact MMB


Legal Notices

Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.