APIs
Overview
Except for basic information, the APIs supported by these endpoints require authentication. A user must login, save the valid certificate data (cookie), and utilize the cookie for subsequent calls to endpoints. Its is expected that the cookie will expire after a set time (default is 10 minutes) and so the usage should be to login, do desired command(s), logout so as to not have the cookie expire. If a cookie does expired, it can take several minutes for the internal state of the web server to reset and allow follow-on logins.
On initial login, the user is required to change the default password and once reset, logoff and login back in with the new credentials.
Unless unreasonable for the endpoint, a JSON result will be provided including SDCERR and InfoMsg elements, as well as applicable data
Example endpoint description and usage
endpoint | the URL endpoint, ie: https://1.2.3.4/endpoint |
---|---|
Method | one of POST/GET/PUT/DELETE |
input format | JSON or in-line parameter |
input | expected variable(s) |
output | expected output |
Endpoints by functional use
Basic information no login required
- definitions - definitions for front-end
- networkStatus - get network status
- version - get system component versions
Credential/user management
System / Wifi
- connections - list current connections
- datetime - get current time/date; get/set timezone
- fips - set desired fips state (if enabled for image)
- file - download log/config/debug files; upload certificate/config file
- files - list certificate files
- firmware - firmware update in block/block mode
- firmware - firmware update in image pulled by server mode (default mode)
- factoryReset - reset to image defaults
- logData - query log data based on settings
- logSetting - set/get logging levels
- networkInterfaces - list network interfaces
- networkStatus - get network status
- reboot - reboot device
WiFi Connection Configurations
- connection - create/replace/remove a network configuration
- file - download log/config/debug files; upload certificate/config file
- files - list certificate files
WiFi settings
- accesspoints - initiate a scan; show cached APs
- awm - enable/disable AP Adaptive Word Mode (default image does not enable this ability)
Positioning
- positioning - set token for position assist/get current location
- positioningSwitch - enable positioning service
Bluetooth / Bluetooth Low Energy (BLE)
- bluetooth - interact with controllers
- get controller(s) state
- bluetooth/controller[n] - interact with specific controller n
- get/set specific controller state
- start/stop TCP server for BLE discovery
- bluetooth/controller[n]/[device_address] - (bt) interact with specific device
- get/set device properties
- start/stop TCP server
- connect/disconnect/read/write/notify BLE device
- bluetooth/controller[n]/[device_address] - (ble) interact with specific device
- connect/disconnect
- read/notify/write
Endpoints - alphabetically
accesspoints
Get cached WiFi access point list
endpoint | accesspoints |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail count: count of access points in array accesspoints: array of access points: SSID Frequency Strength Security InfoMsg: (relevant message |
Initiate a WiFi scan
endpoint | accesspoints |
---|---|
Method | PUT |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message |
return to Overview
AWM
WiFi Geo-location Scanning: AWM - Adaptive World Mode
When the radio’s regulatory domain is configured for World Mode, AWM uses an FCC compliant geo-location algorithm and the 802.11d Country IE to determine the current location and set the regulatory country code of the client radio for optimal performance and regulatory compliance.
The ability to disable WIFI geo-location scanning is an advanced feature that is not enabled on most systems. Geo-location scanning should only be disabled in the rare circumstance that no surrounding Wi-Fi network is broadcasting country code information. Requires a change to the root image to enable this feature.
Set AWM enable/disable
endpoint | awm |
---|---|
Method | PUT |
input format | JSON |
input | geolocation_scanning_enable: 0 – disable 1 - enable |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) geolocation_scanning_enable: 0 – disabled, 1 - enabled |
Get AWM current setting
endpoint | awm |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others - fail InfoMsg: (relevant message) geolocation_scanning_enable: 0 – disabled, 1 - enabled |
return to Overview
connection
The connection endpoint is used to create/delete/activate/deactivate/get info about a connection.
Activate/deactivate
endpoint | connection |
---|---|
Method | PUT |
input format | JSON |
input | uuid: uuid of the connection to be activated activate: 1 – activate, 0 - deactivate |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Get connection details
endpoint | connection?uuid= |
---|---|
Method | GET |
input format | in-line parameter |
input | uuid: uuid of the connection |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Delete a connection
endpoint | connection?uuid= |
---|---|
Method | DELETE |
input format | in-line parameter |
input | uuid: uuid of the connection to be deleted |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Ethernet Configuration
endpoint | connection |
---|---|
Method | POST |
input format | JSON |
input | connection: uuid: back-end will generate an uuid for each connection id: name of the profile type: “802-3-ethernet” interface-name: Ethernet interface name autoconnect: whether enable auto connect zone: firewalld zone to be added to —if part of a bridge, include the following— master: uuid or interface-name of the bridge master slave-type: bridge ipv4: method: one of “disabled”, “auto”, “manual”, “shared”, or “link-local” gateway: dns: address-data: address/prefix ipv6: method: “disabled”, “auto”, “manual”, “dhcp”, “shared”, “ignore”, or “link-local” gateway: dns: address-data: address/prefix |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message |
GSM Configuration
GSM connections are only available on platforms where GSM hardware is present
endpoint | connection |
---|---|
Method | POST |
input format | JSON |
input | connection: uuid: back-end will generate an uuid for each connection id: name of the profile type: “gsm” interface-name: gsmtty1 when cmux is enabled, otherwise ttyS4 autoconnect: whether enable auto connect zone: firewalld zone to be added to —if part of a bridge, include the following— master: uuid or interface-name of the bridge master slave-type: bridge ipv4: method: one of “disabled”, “auto”, “manual”, “shared”, or “link-local” gateway: dns: address-data: address/prefix ipv6: method: “disabled”, “auto”, “manual”, “dhcp”, “shared”, “ignore”, or “link-local” gateway: dns: address-data: address/prefix gsm apn: vzminternet for Verizon |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
WiFi Configuration
endpoint | connection |
---|---|
Method | POST |
input format | JSON |
input | The same ipv4 and ipv6 inputs as Ethernet connection. WiFi specific inputs are listed in the table below. |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message |
WiFi specific connection inputs
id | Name of connection | |
uuid | if left empty, server will generate one | |
type | “802-11-wireless” | |
interface-name | “wlan0” | |
autoconnect | 0/1 | |
master | For bridge mode, Interface name or uuid of the bridge master connection | |
slave-type | “bridge” for bridge mode | |
zone | ||
802-11-wireless | ||
ssid | ssid | |
hidden | 1: indicates the network is a non-broadcasting network that hides its SSID 0: default. Don’t make the network as hidden |
|
mode | “ap” or “infrastructure” | |
client-name | CCX client name | |
tx-power | if non-zero, directs the device to use the specified transmit power. Units are dBm. | |
band | 802.11 frequency band of the network, “a” for 5GHz, “bg” for 2.4GHz. Default is not set. In default case, auto channel selection will work across bands. | |
channel | Wireless channel to use for the Wi-Fi connection for “ap” mode. | |
frequency-list | A string listing the allowed frequencies for AP or station, i.g if only channel 1 and 6 are wanted to setup an AP with ACS, set it to “2412 2437”. | |
powersave | Power saving policy | |
acs | Enable - 1, disable - 0. “frequency-list”, “band’ and “channel”: 1.“frequency-list” has the highest priority – it overrides “band”. 2.If “band” is set, acs shall return “channel” if “channel” is set, otherwise it shall return the “best” channel of the band; 3. if band is not set, acs shall return the “best” channel of both bands. 4. channel 14 shall not be used in any case. |
|
802-11-wireless-security | ||
key-mgmt | “none”, “ieee8021x”, “wpa-psk”, “wpa-eap” | |
auth-alg | When WEP is used, indicate the 802.11 authentication algorithms, one of “open”, “share” or “leap”. | |
wep-tx-keyidx | WEP key index for static WEP | |
proto | rsn or wpa | |
pairwise | ccmp or tkip | |
group | ccmp, tkip, wep40, or wep104 | |
wep-key0 | WEP key 0 | |
wep-key1 | WEP key 1 | |
wep-key2 | WEP key 2 | |
wep-key3 | WEP key 3 | |
leap-username | For legacy LEAP connection | |
leap-password | For legacy LEAP connection | |
psk | Pre-shared key for WPA personal network | |
802-1x | (WPA-enterprise) | |
eap | The allowed EAP method to be used when authenticating to the network with 802.1x. Valid methods are: “leap”, “md5”, “tls”, “peap”, “ttls”, “pwd”, and “fast”. | |
auth-timeout | A timeout for authentication. Zero means the global default; if the global default is not set, the authentication timeout is 25 seconds. | |
tls-disable-time-checks | Disable checking of the server certificates date. | |
phase1-fast-provisioning | Enables or disables in-line provisioning of EAP-FAST credentials when FAST is specified as the EAP method in the “eap” property. Recognized values are “0” (disabled), “1” (allow unauthenticated provisioning), “2” (allow authenticated provisioning), and “3” (allow both authenticated and unauthenticated provisioning). | |
identity | Identity string for EAP authentication methods | |
anonymous-identity | Anonymous identity string for EAP authentication methods. | |
password | UTF-8 encoded password for EAP authentication methods. | |
ca-cert | Contains the CA certificate if used by the EAP method specified in the “eap” property. | |
ca-cert-password | Password to access CA certificate. | |
client-cert | Contains the client certificate if used by the EAP method specified in the “eap” property. | |
client-cert-password | The password used to access a client’s certificate. | |
private-key | Contains the private key when the “eap” property is set to “tls”. | |
private-key-password | The password used to decrypt the private key | |
phase2-auth | Specifies the allowed “phase 2” inner non-EAP authentication method when an EAP method that uses an inner TLS tunnel is specified in the “eap” property. Recognized non-EAP “phase 2” methods are “pap”, “chap”, “mschap”, “mschapv2”, “gtc”, “otp”, “md5”, and “tls”. | |
phase2-autheap | Specifies the allowed “phase 2” inner EAP-based authentication method when an EAP method that uses an inner TLS tunnel is specified in the “eap” property. Recognized EAP-based “phase 2” methods are “md5”, “mschapv2”, “otp”, “gtc”, and “tls”. | |
phase2-ca-cert | Contains the “phase 2” CA certificate if used by the EAP method specified in the “phase2-auth” or “phase2-autheap” properties. | |
phase2-ca-cert-password | The password to access the “phase2” CA certificate | |
phase2-client-cert | Contains the “phase 2” client certificate if used by the EAP method specified in the “phase2-auth” or “phase2-autheap” properties. | |
phase2-client-cert-password | The password used to access the “phase2” client certificate | |
phase2-private-key | Contains the “phase 2” inner private key when the “phase2-auth” or “phase2-autheap” property is set to “tls”. | |
phase2-private-key-password | Password to decrypt the “phase2” private key. | |
pac-file | UTF-8 encoded file path containing PAC for EAP-FAST. | |
pac-file-password | Password to decrypt the PAC file. |
For more information on available settings, refer to NetworkManager User Guide.
Bridge master Configuration
Create or update a bridge master connection. Bridge is a software device. The bridge master must be created prior to adding physical interface slaves to the bridge.
endpoint | connection |
---|---|
Method | POST |
input format | JSON |
input | connection: uuid: back-end will generate an uuid for each connection id: name of the profile type: “bridge” interface-name: one of interfaces listed in the config file. autoconnect: whether enable auto connect zone: firewalld zone to be added to ipv4: method: one of “disabled”, “auto”, “manual”, “shared”, or “link-local” gateway: dns: address-data: address/prefix ipv6: method: “disabled”, “auto”, “manual”, “dhcp”, “shared”, “ignore”, or “link-local” gateway: dns: address-data: address/prefix bridge None for the moment. |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message |
return to Overview
connections
Get all connection profiles
endpoint | connections |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) count: number of connection profiles Connections: array of connections indexed by uuid: id: name of connection activated: 1 – activated, 0 – deactivated type: “ap”, for AP mode only |
return to Overview
datetime
Get date, time, and timezones
endpoint | datetime |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) zones: - alphabetized list of available time zones zone: - current timezone method: auto/manual time: date and time |
Set timezone.
Calling PUT with no timezone will cause the current time/timezone to be returned
endpoint | datetime |
---|---|
Method | Put |
input format | JSON |
input | <optional> zone - desired timezone. |
output | SDCERR: 0 – success, others – fail InfoMsg: current timezone time: current date and time |
return to Overview
definitions
Definitions shared with front-end
endpoint | definitions |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: InfoMsg: Definitions:{ SDCERR: errors may be returned by web server; PERMISSIONS: user permission types to be used by front-end; PLUGINS: plugins to be used by front-end; SETTINGS: settings needed by front-end, including session_timeout; } |
return to Overview
factoryReset
Perform factory reset.
Restores settings/connections to original image.
endpoint | factoryReset |
---|---|
Method | PUT |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: - “Reboot required” |
return to Overview
file
The file endpoint is used for file manipulation. Log, config, and debug files can be downloaded and configurations and certificate files can be uploaded;
Upload Certificate/PAC file
endpoint | file |
Method | POST |
input format | JSON |
input | file: filename type: “cert” or “pac” |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Delete Certificate/PAC file
endpoint | file?type=&file= |
Method | DELETE |
input format | in-line parameter |
input | file: filename type: “config” |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Download encrypted zip file
This is to download a ‘config’, ‘log’ or ‘debug’ file.
The ‘debug’ file is encrypted with a certificate file - default is /etc/weblcm-python/ssl/ca.crt.
Others file types are zipped with password.
endpoint | files?type=&password= |
Method | GET |
input format | in-line parameters |
input | type: one of ‘config’, ‘debug’, or ‘log’ password: password to use for zip |
output | zip file as stream. |
Upload an encrypted zip file.
This is to update the system config directory.
endpoint | file |
Method | POST |
input format | JSON |
input | Password: to unzip file file: filename |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
return to Overview
files
Get available certificate/PAC files
endpoint | files?type= |
---|---|
Method | GET |
input format | in-line parameter |
input | type: “cert” or “pac” |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) files: Array of certificate/PAC files count: number of files in array |
fips
Enable/disable fips/fips_wifi.
Takes effect after reboot.
endpoint | fips |
---|---|
Method | PUT |
input format | JSON |
input | fips: “unset”, “fips” or “fips_wifi” |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Get status of current fips setting
endpoint | fips |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others - fail InfoMsg: (relevant message) status: “fips”, “fips_wifi”. All others shall be considered as “unset”. |
return to Overview
firmware
Firmware Update - block mode
Start firmware update in block mode. Reboot required to take affect after firmware update completed.
endpoint | firmware |
---|---|
Method | POST |
input format | JSON |
input | image: images to be installed, either “main” or “full”. If not set, “main” will be used. |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Send firmware update block
endpoint | firmware |
Method | PUT |
input format | Content type needs to be set to “application/octet-stream”. |
input | Send firmware image block by block - 128K per block; |
output | http stats: 200 - OK, others -fail |
Note: If an http error is returned during octet-stream PUT operations, or after update is complete, GET can be executed on firmware endpoint to check for success and error message, if any.
Check firmware update finished or not after sending the complete image
endpoint | firmware |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – updated, 1– fail, 2– not updating, 5-updating InfoMsg: (relevant message, presently one of “Updated”, “Failed”, “No update in progress”, or “Updating…”, corresponding directly to the SDCERR codes.) |
Note: 0 indicates success, whereas other values indicate a failure or no update initiated. In the event of a failure, start firmware update POST may then be executed and update re-attempted. Please note that in the event of a corrupt image or bad nandflash block, the swupdate library may post a relevant text error message to the syslog. However, the swupdate library does not pass these messages on to the client API. (string field “info” in “C” struct progress_msg from swupdate progress_ipc_receive is always empty, even in the case of a failure with corrupt image and relevant message posted to syslog. The status code supplied is always the generic update failure code.)
Errors are not expected, however, and it may be useful to report error messages to the end user via the GUI if possible, optionally with a “retry” mechanism available.
Abort block mode firmware update
endpoint | firmware |
---|---|
Method | DELETE |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Note: For the 1.0.0.4 API revision, if a block-mode firmware update has been started by POST, all blocks have not yet been sent via octet-stream PUT, and it is desired to abort the update and reset state so as to prepare for a fresh POST, DELETE may be executed.
Firmware Update - Image pulled by device
This API will block a short while in order to start the swupdate service, but will not block during firmware update process. Caller provides address location for device to pull firmware. URLs supported: http/https/ftp/sftp/scp. Reboot required to take affect after firmware update completed.
endpoint | firmware |
---|---|
Method | POST |
input format | JSON |
input | image: images to be installed, either “main” or “full”. If not set, “main” will be used. url: from where firmware is to be downloaded, e.g. http://192.168.1.100/file.swu |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Get firmware update result.
Called if firmware POST operation returns success in order to get updated status
endpoint | firmware |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – updated, 1– fail, 2– not updating, 5-updating InfoMsg: (relevant message) |
Note: 0 indicates success, whereas other values indicate a failure or no update initiated. In the event of a failure, start firmware update POST may then be executed and update re-attempted.
Errors are not expected, however, and it may be useful to report error messages to the end user via the GUI if possible, optionally with a “retry” mechanism available.
release resources
endpoint | firmware |
---|---|
Method | DELETE |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Note: For the 1.0.0.4 API revision, DELETE is deprecated, performs a no-op on the SOM, and is provided only for backwards compatibility.
return to Overview
logData
Query log data based on settings.
endpoint | logData?type=&priority=&days= |
---|---|
Method | GET |
input format | in-line parameters |
input | type: Kernel/NetworkManager/python/All priority: 0-7 days: since 1/2/7/14/30/60/ ago, -1 for all |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) count - number of log entries log: an array of log entries consisting of time, priority, identifier, and message entries. |
return to Overview
login
user login
On first login, the password is required to be changed. (see users - update a password)
endpoint | login |
---|---|
Method | POST |
input format | JSON |
input | username password |
output | SDCERR: 0 -success, others - fail PERMISSIONS: a string of user permission REDIRECT: 1 - password needs to be updated for the first-time login InfoMsg: (relevant message) |
logout user
endpoint | login |
---|---|
Method | DELETE |
input format | <none> |
input | <none> |
output | SDCERR: 0 -success, others - fail InfoMsg: (relevant message) |
return to Overview
logSetting
Set log level for supplicant and driver
endpoint | logSetting |
---|---|
Method | PUT |
input format | JSON |
input | suppDebugLevel: none/error/warning/info/debug/msgdump/excessive driverDebugLevel: 0 – off, 1 - on |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Get log level for supplicant and driver
endpoint | logSetting |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) suppDebugLevel: debug level driverDebugLevel: driver debug level |
return to Overview
networkInterfaces
Get available network interfaces
endpoint | networkInterfaces |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) interfaces: array of interfaces |
return to Overview
networkStatus
Get network status
login not required
endpoint | networkStatus |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 - success, others – fail InfoMsg: (relevant message) devices: number of devices status – array of status of interfaces, including: Status: State: the current state of the device Mtu: maximum transmission unit DeviceType: the general type of the network device connection_active when connection is activated: id uuid interface-name zone: type: “802-3-ethernet”, “802-11-wireless”, “bridge” etc. timestamp: in seconds since the Unix Epoch, that the connection was last successfully fully activated ipv4config: Addresses: Array of IP address data objects. All addresses will include “address” (an IP address string), and “prefix” (a uint). Routes Gateway Domains ipv6config: Addresses Routes Gateway Domains wired if it is an Ethernet connection HwAddress Speed Carrier or wireless if it is a wireless connection: Bitrate HwAddress Mode RegDomain Activeaccesspoint if connected as or to an AP: SSID Hwaddress Strength: The current signal quality of the access point, in percent Frequency: The radio channel frequency in use by the access point, in MHz MaxBitrate: The maximum bitrate this access point is capable of, in kilobits/second Flags: Flags describing the capabilities of the access point. Wpaflags: Flags describing the access point’s capabilities according to WPA Rsnflags: Flags describing the access point’s capabilities according to the RSN Device status is returned by NetworkManager hence subject to the change of NetworkManager. |
return to Overview
positioning
Set token to access positioning assist server
endpoint | positioning |
---|---|
Method | PUT |
input format | JSON |
input | token: string |
output | SDCERR: 0 – success, others – fail |
Get location
endpoint | positioning |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others - fail Positioning: ‘longitude’, ‘latitude’ for celllocate NMEA data for GPS. Weblcm-python forwards what it get from ModemManager and clients is responsible to parse NMEA data. |
return to Overview
positioningSwitch
Enable/disable Celllocate and GPS (exclusive).
Once GPS is enabled, NMEA data will be updated periodically unless it is disabled. For Celllocate, you will get only 1 location data each time, which means you have to disable and then enable again to get an update.
endpoint | positioningSwitch |
---|---|
Method | PUT |
input format | JSON |
input | Source: 0 – disable, 2-celllocate, 4-gps |
output | SDCERR: 0 – success, others – fail source: 0 – disabled, 2 – celllocate is enabled, 4 – gps is enabled |
Get status of location switch
endpoint | positioning |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others - fail source: 0 – disabled, 2 – celllocate is enabled, 4 – gps is enabled |
return to Overview
reboot
Perform a system reboot
endpoint | reboot |
---|---|
Method | PUT |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: - “Reboot initiated” |
return to Overview
users
Get user list
endpoint | users |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) Default_user- default user name Users - list of users other than default user Count - count of non-default users |
Add a user
Default image has max users set to 1. Adding a user requires value to be changed in image configuration.
endpoint | users |
---|---|
Method | POST |
input format | JSON |
input | username: password: permission: |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Delete a user
endpoint | users?username= |
---|---|
Method | DELETE |
input format | in-line parameter |
input | username: user name to be removed |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) |
Update a password
endpoint | users |
---|---|
Method | PUT |
input format | JSON |
input | username: current_password: new_password: |
output | SDCERR: 0 – success, others – fail REDIRECT: 1 – re-login InfoMsg: (relevant message) |
return to Overview
version
Get version information
endpoint | version |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 – success, others – fail InfoMsg: (relevant message) nm_version: NetworkManager version number. weblcm_python_webapp: weblcm version number. build: build number. Shall be the release number unless use a locally built image(in this case shall be 0.x.0.0 + timestamp) supplicant: supplicant version number. driver: WiFi driver used. radio_stack: Laird Radio Stack version kernel_vermagic: Kernel module vermagic value. |
bluetooth
Get controller(s) state
Get bluetooth state of all controllers and discovered devices. Information for all controllers may be requested.
endpoint | bluetooth?filter= |
---|---|
Method | GET |
input format | query string |
input | filter: “bluetoothDevices”, “powered”, “discovering”, “discoverable” |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) controller[0-9]: powered: 1 - powered, 0 - unpowered. discovering: 1 - discovering, 0 - not discovering. discoverable: 1 - discoverable, 0 - not discoverable. bluetoothDevices: array of discovered devices Address Name Paired (1 - paired, 0 - unpaired) Trusted (1 - trusted, 0 - untrusted) RSSI Connected (1 - connected, 0 - disconnected) UUIDs: array of UUIDs provided by device TxPower ManufacturerData: manufacturer-supplied data |
return to Overview
bluetooth/controller[n]
Although many devices have a single Bluetooth controller, the API endpoint scheme supports multiple Bluetooth controllers when present.
Get bluetooth state of first controller and discovered devices.
endpoint | bluetooth/controller0?filter= |
---|---|
Method | GET |
input format | query string |
input | filter: “bluetoothDevices”, “powered”, “discovering”, “discoverable” |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) controller0: powered: 1 - powered, 0 - unpowered. discovering: 1 - discovering, 0 - not discovering. discoverable: 1 - discoverable, 0 - not discoverable. bluetoothDevices: array of discovered devices Address Name Paired (1 - paired, 0 - unpaired) Trusted (1 - trusted, 0 - untrusted) RSSI Connected (1 - connected, 0 - disconnected) UUIDs: array of UUIDs provided by device TxPower ManufacturerData: manufacturer-supplied data |
Set controller state
Set high-level bluetooth controller state, check for open device connections
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | powered: 1 - powered, 0 - unpowered discovering: 1 - discovering, 0 - not discovering discoverable: - 1 discoverable, 0 - not discoverable command: “gattList” or “hidList” |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) GattConnections: optional list of open gatt connections, if command “gattList” issued HidConnections: optional list of open hid connections, if command “hidList” issued |
Application-specific TCP servers for devices
Depending upon the build configuration, application-specific TCP servers may be started for a device. If the relevant functionality is not enabled in a build, these commands will not be recognized.
Virtual Serial Port
Bluetooth low-energy Virtual Serial Port. (A virtual serial port is a pair of gatt characteristics - one notify, and one write - that emulate the functionality of a UART. They may or may not be connected to a hardware UART device. While BLE VSP is not a part of a Bluetooth standard, it may be a common use case.)
BLE TCP server
The BLE API returns data asynchronously. A TCP/IP server may be started to receive notification events asynchronously for Bluetooth low-energy. Events include device discovery, read request responses, write completion, and registered characteristic notification events. It is required to start this server prior to executing certain BLE API commands, such as bleGatt.
Notifications are sent over TCP/IP wrapped as JSON objects.
Start BLE TCP server
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleStartServer tcpPort: port number to start TCP server on (range 1000 to 49151) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Stop BLE TCP server
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleStopServer |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
BLE TCP server status
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleServerStatus |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) started: true if ble tcp server started, false otherwise port: (optional) TCP port server is available on, if started |
Enable BLE WebSockets
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleEnableWebsockets |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
BLE WebSockets Endpoint Availability Test
endpoint | bluetoothWebsocket |
---|---|
Method | GET |
input format | n/a |
output | SDCERR: 0 - WebSocket endpoint available, others - fail InfoMsg: (relevant message) |
BLE WebSockets WebSocket Endpoint
Cookie is required for authentication. See https://en.wikipedia.org/wiki/WebSocket
endpoint | bluetoothWebsocket/ws |
---|---|
Method | GET |
Connection | Upgrade |
input format | WebSocket |
output | streamed WebSocket messages, formatted JSON |
BLE Start discovery
Start device discovery. (Note: Controller must be powered on.) This command in the BLE API is redundant to setting the “discovering” property on the controller REST object.
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleStartDiscovery |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Stop device discovery.
(Note: Controller must be powered on.)
endpoint | bluetooth/controller0 |
---|---|
Method | PUT |
input format | JSON |
input | command: bleStopDiscovery |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
return to Overview
bluetooth/controller[n]/device[device_address] (BT devices)
Devices are referenced by their address with ‘_’ replacing ‘:’ characters.
Get device properties.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | GET |
input format | <none> |
input | <none> |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) Address Name Paired (1 - paired, 0 - unpaired) Trusted (1 - trusted, 0 - untrusted) RSSI Connected (1 - connected, 0 - disconnected) UUIDs: array of UUIDs provided by device TxPower ManufacturerData: manufacturer-supplied data |
Set device properties
- device pairing/unpairing, connect, and trust can be accomplished:
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSONmksdcard.sh |
input | paired (1 – pair, 0 – unpair) trusted (1 – trust, 0 – untrust) connected (1 – connect, 0 – disconnect) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Start VSP TCP server for device
A TCP/IP server may be started on a specified port for a specific BT device. When VSP data is received from this device, it will be passed to the network client connected to the TCP server, if any. Additionally notifications for device “connect”, device “disconnect”, and “transmit failed” may be passed to the network client. When data is received from the network client connected to the TCP server, it will be passed to the VSP device.
Start a TCP server and open BLE VSP (virtual serial port) gatt channel
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: gattConnect tcpPort: port number to start TCP server on (range 1000 to 49151) vspSvcUuid: UUID of the VSP GATT service to connect to (string) vspReadChrUuid: UUID of the VSP GATT service read characteristic (string) vspWriteChrUuid: UUID of the VSP GATT service write characteristic (string) socketRxType: “JSON” - wrap data from BT device as hexadecimal string in JSON (additionally provides “connect”, “disconnect”, “transmit failed” notifications), “raw” - pass binary data from BT device verbatim. Defaults to “JSON”. |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Stop TCP server and close BLE VSP (virtual serial port) gatt channel
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: gattDisconnect |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
HID barcode scanner
Start TCP server to pass read barcodes from device
A TCP/IP server may be started on a specified port for a specific BT HID handheld barcode scanning device. Barcodes scanned by the barcode scanner will be decoded and passed to the network client presently connected to the TCP server, if any. The barcode scanner must be configured for either the BT classic HID protocol, or BLE HID protocol.
Start a TCP server and open BT classic or Bluetooth low-energy (BLE) HID barcode scanner channel
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: hidConnect tcpPort: port number to start TCP server on (range 1000 to 49151) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Shutdown barcode scanning TCP server for device
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: hidDisconnect |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Get connection information for a device
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: getConnInfo |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) rssi: rssi if connected to device (see section 7.5.4 of BLUETOOTH CORE SPECIFICATION Version 5.2, definition differs between BR/EDR and BLE devices) tx_power: tx power associated with device max_tx_power: max tx power associated with device |
bluetooth/controller[n]/device[device_address] (BLE devices)
Connect
Connect to a device. This command in the BLE API is redundant to setting the “connected” property on the device REST object.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: bleConnect |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Disconnect
Disconnect from a device.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: bleDisconnect purge: 0 or false - do not purge, 1 or true - purge device information (unpair / remove) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Read
Read a GATT characteristic and return the data read (if any) asynchronously over the BLE TCP server channel.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: bleGatt operation: read svcUuid: UUID of the GATT service to connect to (string) chrUuid: UUID of the GATT read characteristic (string) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Notify
Notify on GATT characteristic and return the notification data (if any) asynchronously over the BLE TCP server channel.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
Method | PUT |
input format | JSON |
input | command: bleGatt operation: notify enable: 0 or false - disable notifications, 1 or true - enable notifications svcUuid: UUID of the GATT service to connect to (string) chrUuid: UUID of the GATT notify characteristic (string) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |
Write
Write GATT characteristic and notify upon completion asynchronously over the BLE TCP server channel.
endpoint | bluetooth/controller0/xx_xx_xx_xx_xx_xx [address of device, as provided in device array, “:” → “_” ] |
---|---|
summary | Write GATT characteristic, and notify over BLE TCP server. |
Method | PUT |
input format | JSON |
input | command: bleGatt operation: write value: data encoded as a hexadecimal string svcUuid: UUID of the GATT service to connect to (string) chrUuid: UUID of the GATT write characteristic (string) |
output | SDCERR: 0 - success, others - fail InfoMsg: (relevant message) |