-
Notifications
You must be signed in to change notification settings - Fork 19
USB Communication
Communication between the AudioMoth device and a host computer uses a vendor-specific USB HID protocol using VID = 0x10C4 and PID = 0x0002. The protocol allows the exchange of a 64-byte packet every millisecond. A small number of standard messages are predefined and these are automatically handled by the AudioMoth library. In each case, the first byte of the packet indicates the message type, and this message type is echoed back in the first byte of the response from the AudioMoth device.
Sending a packet with the first byte set to zero allows the USB communication with the AudioMoth device to tested.
+---+
Sent | 0 |
+---+
+---+
Response | 0 |
+---+
The USB host may request the time from the AudioMoth device. The response is a 4-byte little endian Unix timestamp.
+---+
Sent | 1 |
+---+
+---+------------+
Response | 1 | UNIX Time |
+---+------------+
The USB host may set the time on the AudioMoth device. The time is sent as a 4-byte little endian Unix timestamp and is echoed back by the AudioMoth device.
+---+------------+
Sent | 2 | UNIX Time |
+---+------------+
+---+------------+
Response | 2 | UNIX Time |
+---+------------+
The USB host may request the unique ID of the AudioMoth device. The response is a 8-byte ID.
+---+
Sent | 3 |
+---+
+---+------------------------+
Response | 3 | 8-byte UID |
+---+------------------------+
The USB host may request the battery state of the AudioMoth device.
+---+
Sent | 4 |
+---+
+---+---+
Response | 4 | b |
+---+---+
The response is a single byte with value between 0 and 15 corresponding to the following enumeration.
typedef enum {AM_BATTERY_LOW, AM_BATTERY_3V6, AM_BATTERY_3V7, AM_BATTERY_3V8,
AM_BATTERY_3V9, AM_BATTERY_4V0, AM_BATTERY_4V1, AM_BATTERY_4V2,
AM_BATTERY_4V3, AM_BATTERY_4V4, AM_BATTERY_4V5, AM_BATTERY_4V6,
AM_BATTERY_4V7, AM_BATTERY_4V8, AM_BATTERY_4V9,
AM_BATTERY_FULL } AM_batteryState_t;The USB host may request an application specific packet from the AudioMoth device. The AudioMoth library handles the echoing of the message type and calls AudioMoth_usbApplicationPacketRequested to request that the application provide the custom payload.
+---+
Sent | 5 |
+---+
+---+-------------------------------+
Response | 5 | Custom Payload |
+---+-------------------------------+
The USB host may send an application specific packet to. The AudioMoth library handles the echoing of the message type and calls AudioMoth_usbApplicationPacketReceived to allow the application to handle the custom payload. The application can choose to echo back the custom payload or provide any other response that the particular application requires.
+---+-------------------------------+
Sent | 6 | Custom Payload |
+---+-------------------------------+
+---+-------------------------------+
Response | 6 | Optional Custom Payload |
+---+-------------------------------+
The USB host may request the current firmware version from the AudioMoth device. The response is a 3-byte number in 3 parts, using the semantic versioning system (e.g. 1.0.2). The AudioMoth library handles the request and calls AudioMoth_usbFirmwareVersionRequested, expecting a pointer to a 3-byte version number.
+---+
Sent | 7 |
+---+
+---+------------------+
Response | 7 | Version number |
+---+------------------+
The USB host may request a short description of the current firmware from the AudioMoth device. The response can be up to 32 bytes, terminating in a null character. The AudioMoth library handles the request and calls AudioMoth_usbFirmwareDescriptionRequested, expecting a string of up to 32 bytes in length containing a brief description of the firmware (e.g. "AudioMoth-Basic-Bat-Detector").
+---+
Sent | 8 |
+---+
+---+------------------------+
Response | 8 | Firmware description |
+---+------------------------+
The USB host may query is automatic switching to the bootloader is supported.
+---+
Sent | 9 |
+---+
+---+---+
Response | 9 | b |
+---+---+
The response is a single byte with value either 0 or 1 if the option is supported.
The USB host may request that the AudioMoth switch to bootloader mode.
+---+
Sent | A |
+---+
+---+---+
Response | A | b |
+---+---+
The response is a single byte with value either 0 or 1 if the request is actioned.