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

Credential/user management

  • login - login/logout
  • users - change password; list/add/remove users

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

Bluetooth / Bluetooth Low Energy (BLE)


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

examples: curl / python

Initiate a WiFi scan

endpoint accesspoints
Method PUT
input format <none>
input <none>
output SDCERR: 0 – success, others – fail
InfoMsg: (relevant message

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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.

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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;
}

examples: curl / python

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”

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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.

examples: curl / python

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: filenametype: "config"
output SDCERR: 0 – success, others – fail
InfoMsg: (relevant message)

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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”.

examples: curl / python

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)

examples: curl / python

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

examples: curl / python

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.)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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.

examples: curl / python

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)

examples: curl / python

logout user

endpoint login
Method DELETE
input format <none>
input <none>
output SDCERR: 0 -success, others - fail
InfoMsg: (relevant message)

examples: curl / python

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)

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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.

examples: curl / python

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

examples: curl / python

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.

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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”

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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.

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

Stop BLE TCP server

endpoint bluetooth/controller0
Method PUT
input format JSON
input command: bleStopServer
output SDCERR: 0 - success, others - fail
InfoMsg: (relevant message)

examples: curl / python

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

examples: curl / python

Enable BLE WebSockets

endpoint bluetooth/controller0
Method PUT
input format JSON
input command: bleEnableWebsockets
output SDCERR: 0 - success, others - fail
InfoMsg: (relevant message)

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

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)

examples: curl / python

return to Overview