Devices that don't have a direct internet connection can connect to the remote management service over serial. This is done via the serial daemon, which is an application that runs on a host machine. The serial daemon connects to a device over a serial port, and sends AT commands back and forth to the device. If your device implements all AT commands on this page, the serial daemon should work as-is on your device.
Communication between host and device is done with the following settings:
Baud rate 115200.
Data bits: 8.
Return key: CR.
A comprehensive test suite for devices implementing this protocol is located here: edgeimpulse/integration-tests-firmware.
This overview should be printed when AT+HELP is issued.
It's allowed to add custom commands. For example, these commands are implemented in the Edge Impulse firmware for the ST B-L475E-IOT01A, but are not used by the serial daemon.
Clears the complete configuration, and resets the system. Has no return value. Example:
Afterwards all settings should be reset.
Restarts the system, but leaves all configuration intact. Has no return value. Example:
Lists all configuration options, grouped by category. Lines with category names start and end with =====. Lines with configuration options follow key: value, with arbitrary whitespace between : and the value. Example:
See the separate sections per configuration option below for more information.
Returns information about the device and the firmware. The ID here should be a globally unique ID (like a MAC address). If the device does not have a globally unique ID set this to 00:00:00:00:00:00 and implement the AT+DEVICEID command. The serial daemon will then use the MAC address of the USB controller instead.
The Data Transfer Baudrate is the baud rate that the device can switch to when offloading data for functions like AT+BUFFER. If the device does not support switching to a higher baud rate set this to 115200. See "Switching to higher baud rates" later on this page for the protocol.
Example:
For an overview of the different AT command versions, see the end of this page.
Sets the device ID. This is only required for devices that do not have a globally unique ID (see AT+DEVICEINFO?).
Example:
Lists sensors on the device that can be used to collect data. One sensor per line, with Name, Max sample length, and Frequencies listed. The name that you list here will be passed back to AT+SAMPLESTART= to indicate which sensor should be used. Example:
Lists whether the device has a camera, whether the device supports snapshot streaming, and the resolutions of the camera. If the device does not have a camera set Has snapshot to 0 and omit the other options. The color depth should be either Grayscale or RGB. Example:
No file system? The serial daemon can also use a scratch buffer instead, e.g. on external or internal flash. For this you need to implement the AT+READBUFFER function and follow the instructions under AT+SAMPLESTART.
Lists all files on the file system, one file per line. Example:
Read a single file from file system, returns the full file in base64 format. This function takes two parameters: 1) the name of the file, 2) whether to switch to the 'Data transfer baud rate' (y/n). Example:
If the file does not exist, a string should be returned such as:
Removes a single file from file system. Returns nothing if the file was unlinked successfully. Example:
If the file does not exist, or if unlink fails, a string should be returned:
Uploads a file to Edge Impulse. This uses the upload settings (see AT+UPLOADSETTINGS?) to specify where the file will be sent. Once uploading is completed, the device should respond with File uploaded. Example:
If the file does not exist, an error should be thrown that starts with "Failed to upload file". Example:
If there's no WiFi connection, an error should be thrown that starts with "Not connected to WiFi". Example:
Clears all files on the underlying file system, except the config file. Example:
Read part of the scratch buffer, and returns this data in base64 format. This function takes three parameters: 1) the start offset, 2) the end offset, 3) whether to switch to the 'Data transfer baud rate' (y/n). Example:
An integer is used to specify the security mode for a WiFi network, according to this list:
0 - Open access point
1 - WEP
2 - WPA
3 - WPA2
4 - WPA/WPA2
5 - PPP authentication context
6 - PPP authentication context
7 - EAP-TLS
8 - PEAP
255 - Unknown
Scans for nearby WiFi networks. Returns one network per line. Example:
Lists current WiFi credentials, MAC address, and whether the device is connected. Example:
No WiFi? Return 0 for 'Present' and leave the other fields empty. The serial daemon will then no longer prompt to connect the development board to WiFi.
Sets WiFi credentials. Takes three parameters: SSID, password, and security mode (integer). After calling this function the device connects to the WiFi network, gets NTP info, and connects to the remote management service (if the remote management settings are set). Returns OK when done. Example:
Note: failure to connect to the remote management service should not throw an error, and should still return OK.
Lists the current sample settings, such as the label to use, the interval, the length and the HMAC key. Example:
Sets the current sample settings. This either takes three parameters (label, interval, length) or four parameters (label, interval, length, HMAC key). Returns OK. Example:
Note that the interval may be ignore if the sensor does not support this. E.g. if a microphone only supports sampling at 16KHz it will ignore this setting.
Lists the current upload settings, such as the API Key (used to authenticate to the ingestion service, but also used for connecting to the remote management service). Example:
Sets the upload and remote management API key and sets the path (two parameters). Returns OK. Example:
Sets the upload host. Returns OK. Example:
Lists the current settings and state for the remote management service. Note that the API key used to authenticate to the service is set by AT+UPLOADSETTINGS=. If the device is not connected, the Last error field can be used to indicate why the connection failed. Example:
Or when something went wrong:
Sets the management URL. After this value is changed the device should not disconnect from the current remote management service - this only happens after re-connecting to WiFi or when restarting the device. Returns OK. Example:
Starts sampling according to the parameters in AT+SAMPLESETTINGS?, and then uploads the file (if connected to WiFi) according to the parameters in AT+UPLOADSETTINGS?. Takes one parameter, the name of the sensor (one of the sensors listed in AT+SENSORS?).
If the upload succeeds, you can unlink the file to save space. If the device is not connected to WiFi it should print the string Not uploading file. The serial daemon will then use AT+READFILE with the file name specified earlier to read the file back.
If you have stored the file in a scratch buffer - e.g. on external flash - without a file system, you need to print: Not uploading file. Used buffer, from=0, to=310. (where 0 and 310 are parameters that will be passed in to AT+READBUFFER).
The sample interval from AT+SAMPLESETTINGS? may be ignored, e.g. if this is set to a value that the sensor does not support.
While sampling you can print the following lines to give feedback about the sampling status. These messages are intercepted by the daemon and used to set UI updates in the studio.
Sampling... - sampling has started, currently recording data from the sensor.
Done sampling - sampling has finished.
Processing... - if the sample requires post-processing (e.g. signing the file, or copying the file over), send this event.
Done processing - post-processing was done.
Uploading... - uploading has started.
OK - full process is done.
If the device is not connected, end with the line Not uploading file, and don't emit OK.
Prior to starting, please print out a line that starts with File name: and lists where the file will be stored.
Example:
Makes a photo and prints the frame buffer as a base64 encoded string. This function takes three parameters: 1) the width of the snapshot, 2) the height of the snapshot, 3) whether to switch to the 'Data transfer baud rate' (y/n). The content of the base64 buffer should be a uint8_t array, with one value per pixel when in grayscale mode, or three values per pixel in RGB mode. E.g. an 2x1 image with a black and a white pixel would be:
Grayscale: [ 0x00, 0xff ] (pixel 1, pixel 2).
RGB: [ 0x00, 0x00, 0x00, 0xff, 0xff, 0xff ] (pixel 1 red, pixel 1 green, pixel 1 blue, pixel 2 red, pixel 2 green, pixel 2 blue).
Example:
To decode the framebuffer you can use the edge-impulse-framebuffer2jpg tool which is part of the Edge Impulse CLI. Write the base64 string to a file called features.txt and then invoke:
This will create a file called framebuffer.jpg with the decoded content.
Constantly snaps photos and prints the frame buffer as a base64 encoded string, until b is received on stdin. This function takes three parameters: 1) the width of the snapshot, 2) the height of the snapshot, 3) whether to switch to the 'Data transfer baud rate' (y/n). The format is the same as AT+SNAPSHOT, but every snapshot should be on a new line.
Example:
For commands that allow switching to a higher baud rate (AT+READFILE, AT+READBUFFER, AT+SNAPSHOT, AT+SNAPSHOTSTREAM) you'll need to follow this procedure:
When n is passed in for the 'use max rate' property:
Do nothing, just print as usual.
When y is passed in for the 'use max rate' property:
Print \r\nOK on baud rate 115,200.
Wait 100ms and switch to the max. baud rate. This gives the serial daemon time to switch the rate.
Print the result of the command.
Print \r\nOK (on the max. baud rate).
Wait 100ms. and switch back to baud rate 115,200.
Print a new REPL start line (\r\n> ).
1.2.0 - switch the return type of AT+READFILE from hex to base64.
1.3.0 - implement AT+READBUFFER and the Present field for WiFi.
1.4.0 - add snapshot mode and the data transfer baud rate property.
1.5.0 - add snapshot streaming mode.
1.6.0 - allow explicit switching to higher baud rates.