Bluetooth and Tympan Rev F

The Tympan is an open source device for audio processing. At the heart of the Tympan is a Teensy 4.1, which the user can program with their own audio processing algorithms by building upon the Tympan_Library. In addition to the Teensy 4.1, the Tympan also includes a Bluetooth module so that the user can control their Tympan using their phone or tablet.

Tympan_nRF52840

In the Tympan Rev F, the Bluetooth module is an nRF52840. The Teensy 4.1 and the nRF52840 communicate with each other over a serial (UART) connection. The nRF52840 has its own firmware, which can be changed to allow for new or improved capabilities. We wrote the Tympan nRF52840 firmware by building upon the nRF52 library from Adafruit.

This document was written by the Tympan team to capture the requirements that it set for the nRF52840 firmware in the Tympan Rev F.

Requirements for BLE Firmware (for nRF52840)

Overview

The nRF52840 must act as a data bridge between an external device (like a smartphone) and the main processor in the Teensy 4.1 that is at the heart of the Tympan Rev F. The nRF52840, therefore, must have firmware that addresses these interfaces:

BLE Link to External Device: Obviously, the link between the nRF52840 and the external device is via BLE. Therefore, the nRF52840 needs firmware to execute all of the relevant BLE functions.
UART Link to Tympan Processor: The link between he nRF52840 and the Tympan processor is via serial UART. Therefore, the nRF52840 needs firmware to send and receive messages via the UART link and to have those messages interact with the BLE setup or BLE communication functions.
GPIO Pins: In addition to these primary interfaces, the nRF unit is connected to the Tympan process through a number of GPIO pins. The nRF hardware and our nRF firmware can interact with these GPIO pins to achieve a wide variety of functions including: setting up a secondary serial communication interface, reading nRF state, commanding nRF state.

The sections below describe the implementation of these three interfaces.

BLE Functions

The following functions are required for the nRF52840 to manage and use its connections via BLE to an external device (like a phone):

Support the Tympan-Specific Service: To appear in the Tympan Remote App, the Tympan's bluetooth module (ie, the nRF52840) must offer and advertise the service UUID that the Tympan Remote app expects.
Present a Custom Name: When advertising, the nRF52840 firmware must allow us to set what name is shown for the device.
Connect to Remote Device: The nRF52840 must handle the full connection process.
Transmit out to BLE: The nRF52840 must be able to transmit bytes out via BLE to the remote device
Receive in from BLE: The nRF52840 must be able to receive bytes via BLE in from the remote device

The following functions are desired (but not required) for BLE for the Tympan:

Over-the-Air Firmware Updating: To enable the nRF firmware to be updated without the physical programming nest, it is desired that the nRF58240 continue to offer the service that allows firmware to be updated over-the-air (OTA).
Turn Off BLE: It is desirable to be able to power off or silence the radio emissions from the nRF52840. (Note, by having the Tympan processor command the nRF_RESET pin to a certain state, it may be possible to achieve this same goal.)
Support the nRF UART Service: To enable the Tympan to also be usable from the Adafruit Bluefruit Connect app as well as the Nordic nRF Connect app, it is desired to have the nRF52840 also offers the nRF UART service. Ideally, it would also advertise this service, but it is not known whether it is technically feasible to simultaneously advertise both the Tympan-specific service as well as the nRF UART service. (Note, as of April 2024, the system supports the nRF UART service but is not able to include it in the BLE advertising. Because we do support the service (we just don't advertise it), The Adafruit App still easily connects to our device.)
Support Pre-Defined BLE Services, Invoked as Presets: Perhaps a Tympan user would like employ other BLE services besides UART, the BLE support for Tympan should allow access to selected BLE services as presets that can be invoked.
Support Arbitrary, Custom BLE Services, Definable From Tympan: Perhaps a Tympan user would like employ other BLE services besides the presets described above, the BLE support for Tympan should allow the Tympan user to define their own BLE services and BLE characteristics. (As of Feb 2025, this goal is desirable, but it is an advanced capability that is NOT being actively developed.)

UART Functions

The following functions are required for the nRF52840 to manage and use its UART connection back to the Tympan processor:

Serial Format: All communication over the UART link will be in 8-bits, no parity bit, and 1 stop bit ("8-N-1").
Baud Rate: Communication over the UART link shall start at a documented baud rate. The baseline value is 115200bps unless documented elsewhere.
Consistent Starting State: All configurable parameters of the nRF UART link (such as the baud rate) shall always start at the same values, regardless of any changes to the baud rate that might have been commanded in a previous session. As a result, no "factory reset" function should be necessary as the nRF unit should always start at its "factory" (ie, Tympan/Creare) pre-defined configuration.
Messages vs Data Payload: There are two types of communication that might occur over the UART link. The first type of communication are "messages" that are intended to be between the Tympan and the nRF unit itself. The second type of communication are "Data Payload" that is intended to be conveyed between the Tympan and the remote device through the nRF unit.
A Message: A message to or from the nRF52840 is defined as a string of bytes (up to 255 bytes) preceded by a preamble string (ex: "OK" or "FAIL") optionally followed by additional message bytes, and finally terminated by a carriage return ('\r'). Most bytes are expected to be characters that are human-readable in a serial monitor (assumed ASCII).
Message Acknowledgement: Every message from the Tympan to the nRF shall be acknowledged with a responding message from the nRF. At minimum, the acknowledgement will consist of a preamble word ("OK" or "FAIL") and be terminated by a carriage return. In contrast, the nRF unit expects no acknowledgement from the Tympan.
A Data Payload: All communication from the Tympan will be in the form of messages (ie, start with a preamble word and end in a carriage return). Most messages from the nRF unti will also be in the form of messages. But, in the case of data coming to the nRF from its BLE link to an external device, any such bytes will be conveyed to the Tympan via UART with no additional formatting. This "data payload" will have no preamble nor any terminating carriage return, unless that is part of the message supplied by the external device. Therefore, if the Tympan receives any bytes that are either (1) not immediately in response to a Tympan message or (2) lack a preamble word, the Tympan can assume that the bytes are data received over the BLE link. Note that the Tympan cannot send such unformatted data back to through the nRF unit. Instead, see the "SEND" verb.
Message Structure: VERB and DATA: All messages to the nRF shall consist of a verb followed optionally by additional message data. The verb and data shall be separated by a space character. The whole message, of course, shall also be terminated by a carriage return. Example messages to from the Tympan to the nRF are: "GET VERSION" or "SET NAME=TYMPAN42" (each with a trailing carriage return)
nRF Response Format: As mentioned in the "Message Acknowledgement" section, the nRF shall reply to every message from the Tympan with an acknowledgement message. Being a "message", this acknowledgement shall have a pre-amble word, optionally some data bytes, and terminate in a carriage return. The pre-amble word shall be either positive ("OK") or negative ("FAIL"). Any additional message (such as the data being requested by the Tympan), the additional data bytes shall follow the preamble word, with a space in between. Example response messages from the nRF to the Tympan are: "OK", "FAIL COMMAND UNKNOWN", or "OK VERSION 1.0.1, MAR 3, 2024".

Valid commands from the Tympan to the nRF52840 via the UART link are:

BEGIN [value]: This command starts all of the BLE services enabled by default and/or by the user. Any change to the MAC address or BLE services must occur prior to sending this command. One may provide an optional value, which is currently ignored, but might be used in he future.
GET [parameter]: This command gets the value associated with the specified configuration parameter
SET [parameter]=[value]: This command sets the specified configuration parameter to the value provided
SEND [data bytes]: This command tells the nRF52840 to send the specified bytes. Data bytes must exclude the '\r' byte. Message must end with a carriage return.
BLEWRITE [SERVICE_ID] [CHAR_ID] [NBYTES] [data bytes]: This command tells the nRF52840 to send the specified data bytes via a BLE "write" command to the specified BLE service and characteristic ID. The SERVICE_ID, CHAR_ID, and NBYTES are single characters holding the ID number. The data bytes can include any bytes (including '\r'). Finally, as with any message, it must be terminated in a carriage return (which is excluded NBYTES used to describe the length of the data bytes). An example would be "WRITE 2 0 4 xxxx", which specifies that we're sending to the 2th service and the 0th characteristic, that we're sending 4 bytes, and which is followed by the 4 bytes (such as representing a 32-bit integer). Don't forget that the whole message must include a trailing carriage return.
BLENOTIFY [SERVICE_ID] [CHAR_ID] [NBYTES] [data bytes]: This command tells the nRF52840 to send the specified data bytes via a BLE "notify" command to the specified BLE service and characteristic ID. The format is the same as the WRITE command above. An example would be "NOTIFY 0 0 1 x", which specifies that we're sending to the 0th service and the 0th characteristic, that we're sending 1 byte, and which is followed by the 1 byte. Don't forget that the whole message must include a trailing carriage return.

Valid parameters to use with GET and SET include:

Future parameters to use with GET and SET will include:

SERVICE_ID1: The user can get or set the service UUID for the first advertising slot. Example: "SET SERVICE_ID1=BC2F4CC6AAEF43519034D66268E328F0"
SERVICE_ID2: The user can get or set the service UUID for the second advertising slot. Example: "SET SERVICE_ID2=BC2F4CC6AAEF43519034D66268E328F0"
CHARACTERISTIC_ID1: The user can get or set the characteristic UUID for the first service. Example: "SET CHARACTERISTIC_ID1=06D1E5E779AD4A718FAA373789F7D93C"
CHARACTERISTIC_ID2: The user can get or set the UUID for the second service. Example: "SET ADVERTISING_SERVICE_ID1=06D1E5E779AD4A718FAA373789F7D93C"

GPIO Functions

The nRF unit is connected to the Tympan processor through a number of GPIO pins. The table below describes the functionality of the pins.

Net Name	Teensy Pin	nRF Pin	Function(s)	Implemented?
BT_nRESET	9	P0.18	Pull LOW to reset nRF unit	Yes
BT_RX	28	D1	UART Serial Data	Yes
BT_TX	29	D0	UART Serial Data	Yes
BT_RTS	0	D9	UART Flow Control (or GPIO)	No
BT_CTS	1	D10	UART Flow Control (or GPIO)	No
LRCLK2	3	D18	I2S Interface (or GPIO)	No
BCLK2	4	D17	I2S Interface (or GPIO)	No
MISO1	12	D25	SPI Interface (or GPIO)	nRF Out: HIGH = Connected
MOSI1	13	D26	SPI Interface (or GPIO)	No
SCK1	19	D24	SPI Interface (or GPIO)	No
BT_CS	38	D8	SPI Interface (or GPIO)	No
LED_0	N/A	D14	nRF-Controlled LED (Red)	Yes
LED_1	N/A	D12	nRF-Controlled LED (Blue)	Yes
LED_2	N/A	D15	nRF-Controlled LED (Green)	Yes

Provide feedback

Saved searches