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

• 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

• 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

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, Laird’s 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 Laird 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

Check firmware update finished or not after sending the complete image

endpoint	firmware?mode=0
Method	GET
input format	<none>
input	<none>
output	SDCERR: 0 – success, others – fail InfoMsg: (relevant message)

examples: curl / python

Cleanup after firmware update

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

examples: curl / python

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?mode=1
Method	GET
input format	<none>
input	<none>
output	SDCERR: 0 – updated, 1– fail, 5-updating InfoMsg: (relevant message)

examples: curl / python

release resources

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

examples: curl / python

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: gattDisonnect
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: hidDisonnect
output	SDCERR: 0 - success, others - fail InfoMsg: (relevant message)

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