When the code starts to run, a task is created for the main application. The device task application consists of three states as shown in the following figure table:
SPS server is disabled, database creation has started
APP_CONNECTABLE
Database is created, SPS server is enabled, advertising started
APP_CONNECTED
Advertising stopped, a central device connected
The first state is APP_DISABLED. During this state the SPS server is being enabled, the UART baudrate is set, and the database for the SPS server is created.
The database is kept in the server’s profile and its service and characteristics are described in Serial Port Service (SPS).
After the database is created, the advertising procedure begins. This means that the device advertises the SPS server UUID.
Also two linked lists with zero members are allocated, which will be used for data scheduling.
The first list, which will from now on be called Rx list, holds buffers received by the UART and that wait to be transmitted by the BLE interface. The second list, which will from now on be called Tx list, holds buffers received by the BLE interface and that wait to be transmitted by the UART.
Details about data scheduling are described in Data Scheduling.
Now the device is in APP_CONNECTABLE state and any host that also supports the serial port service can connect to it.
During the connection procedure if the device gets an invalid connection id, the device returns to APP_CONNECTABLE state.
Otherwise, the device enters APP_CONNECTED state and the advertising stops, the created profiles and services are enabled, gets the features of the host device and starts the param update procedure.
After completion of the parameter update the data length is set, the default tx size, and finally the MTU exchange procedure starts.
Afterwards, independent of the sleep mode that is used (by default the device is in mode sleep on), the following initializations take place:
Set the default tx size to 244.
Initialize the UART and the DMA channels for the specific connection.
Allocate a DMA Rx buffer and trigger to read from DMA.
Set UART RTS pin to low in order to be ready to receive data.
Now the device is ready to receive or send data. Therefore, the device starts asynchronous checks to see either if data are available from BLE to send to the UART Tx queue,
or data are available from the UART Rx queue to send over BLE. More details about data scheduling are described in Data Scheduling.
In case a disconnection takes place, the following things will happen:
Set the tx size to 23
Advertising starts again and a device task application enters APP_CONNECTABLE state
If there is data to be send over BLE, this data will not be lost, but stored in the Rx list queue, in order to continue to send them to the host device when reconnected
UART RTS pin is set to high in order not to receive or send any data from/to the UART interface
The DMA UART Rx channel is being deactivated
The device application task state machine is shown in following figure:
Database is created, SPS client is enabled, scanning started.
APP_CONNECTED
Scanning stopped, connected to a device.
The first state is APP_DISABLED. During this state SPS client is being enabled, UART baudrate is set, and the database for the SPS client is created. The database consists of the same characteristics as the server’s database, described in Data Scheduling.
After database creation finishes the scan procedure begins, where the host scans in order to find a device that supports SPS to connect to it. Now the host enters APP_CONNECTABLE state.
Also two linked lists with zero members are allocated, which will be used for data scheduling. One list for Tx and one for Rx. The data scheduling process is described in Data Scheduling.
If the host cannot connect to the desired device, the scan procedure stops after some time and restarts again. If the host connects successfully to a device it enters to APP_CONNECTED state. Scanning stops and the created profiles and services are enabled.
Afterwards, independent of the sleep mode that is used (by default the device is in sleep on mode), the following initializations take place:
Set the default tx size to 244
Initialize the UART and the DMA channels for the specific connection
Allocate a DMA Rx buffer and trigger to read from DMA
Set UART RTS pin to low in order to be ready to receive data
Now the device is ready to receive or send data. Therefore, the device starts asynchronous checks to see either if there is data available from BLE to send to the UART Tx queue, or if there is data available from the UART Rx queue to send over BLE. More details about data scheduling are described in Data Scheduling.
In case a disconnection takes place, the following things will happen:
Scanning starts again and the device task application enters APP_CONNECTABLE state Set the tx size to 23
Scanning starts again and the device task application enters APP_CONNECTABLE state
If there is data to be send over BLE, this data will not be lost, but stored in the Rx list queue, in order to continue to send them to the device when reconnected
Set UART RTS pin to high in order not to receive or send any data from/to the UART interface
The DMA UART Rx channel is being deactivated
The host application task state machine is shown in Figure blow:
The data scheduling mechanism is implemented in the application task layer. The data flow can be split in two parts:
Data received by UART and transmitted to the BLE interface (UART-> BLE)
Data received over the BLE interface and transmitted to the UART interface (BLE->UART)
In order to protect the data flow either from UART overflow (UART FIFO is 16 bytes) or heap exhaustion in BLE traffic and possible data loss or system hangs, the use of a Flow control mechanism is necessary. The BLE flow control mechanism is described in detail in BLE Flow Control.
This section describes data scheduling for the host and the device.
At the startup two linked lists with zero members are allocated. The first list, Rx list, holds buffers received by the UART and wait to be transmitted by the BLE interface. The second list, Tx list, holds buffers received by the BLE interface and wait to be transmitted by the UART.
In order to minimize data copying and the allocation of heap memory, a buffer optimization scheme is used. The buffers received by DMA UART are put in the Rx list. When data scheduling is done the buffers are detached from the linked list and forwarded from the user space to the profile for transmission.
For the data received over the UART interface, an asynchronous process checks the presence of pending buffers in the Rx list and when there is no data transfer ongoing, it pushes the buffer to the BLE.
When the transfer of buffers over DMA is complete on the UART DMA receive path, an Rx callback puts the new buffer at the end of the Rx list and if the flow of data is not disabled, reinitiates the read of UART via DMA.
Note
DA1453x
The application reads the current heap usage and if the used heap is more than approximately 57%, the device enters flow off state. This means that the RTS signal is high and remains high until heap usage becomes lower than approximately 575%. Then the device enters the flow on state and is able to receive data again on the DMA UART interface.
The flow control signaling on the BLE interface is also triggered when the corresponding flow control signal is received from the UART interface. The dma_uart_gpio_callback is triggered when the host CTS signal is toggled. This function sends
The buffers that the BLE receives are put in the Tx list. When data scheduling is done, the buffers are detached from the linked list and are forwarded from the user space to DMA for transmission over UART.
An asynchronous process checks the presence of pending buffers in the Tx list and when there is no data transfer ongoing, a transfer to the UART is initiated.
On the UART DMA transmit path a Tx callback is called when the transmission of a buffer over UART is complete. The callback checks if more buffers exist in the Tx list and reinitiates the transfer with a detached buffer from the Tx list.
To decide if the Rx of data from the BLE peer should be blocked (flow off) or be continued (flow on), a buffer utilization level for the Tx linked list is defined.
If the contents in the Tx list are more than the upper buffer utilization level, a BLE FLOW_OFF packet is sent to peer’s BLE in order to block traffic from BLE.
If the contents in the Tx list are fewer than the lower buffer utilization level, a BLE FLOW_ON packet is sent to the peer’s BLE in order to allow the BLE to continue to send traffic.
BLE traffic is regulated and blocked with the BLE Flow Control mechanism when the device receives traffic over BLE. The flow control mechanism depends on the current heap usage. The flow control mechanism is enabled in code with the following definitions:
CFG_BLE_FLOW_CONTROL: Enables the flow control mechanism
CFG_LOG_HEAP_LOG: Gets the current heap usage
Important
The BLE Flow control mechanism consists of three states:
DISABLED: when the heap usage level is below 47%*
REDUCED: when the heap usage level is between 52% and 63%*
When the BLE Flow Control mechanism is in DISABLED state, the BLE subsystem receives all the packets properly sent from the peer device.
When the BLE Flow Control mechanism is in REDUCED state, the BLE subsystem receives some of the packets properly sent from the peer device. This triggers the BLE subsystem to NACK other packets that are not received, thus leading the remote peer to do a retransmission. Since the remote peer is properly notified of the NACK, normally it will not trigger a connection timeout on its side. In this state the user can configure how many packets to NACK.
When the BLE Flow Control mechanism is in BLOCKED state , the BLE subsystem is forced to not receive the packets properly sent from the peer device.
This triggers the BLE subsystem to NACK the packets received, thus leading the remote peer to do a retransmission. Since the remote peer is properly notified of the NACK, normally it will not trigger a connection timeout on its side.
But since the device stack does not receive proper BLE packets, its default behavior would lead to a connection timeout. For this reason, the following custom operation has been added: when an incoming BLE packet is detected, the connection timeout period in the BLE stack is reloaded.
Also, since the BLE subsystem does not receive proper packets, it cannot determine the SN, NESN of the last packet sent by the remote peer, so it cannot prepare and send packets to the remote peer.
The Serial Port Service (SPS) emulates serial cable communication. SPS is used to send and receive data, and software flow control signals through a BLE connection. The BLE database has two 250-byte characteristics for serial data transmission and reception, and a one byte characteristic for the flow control.128-bit UUIDs are used for the service and the characteristics.
The Serial Port Service uses a ‘Write with no response’ method for the transmission of data from the GATT client to the GATT server, and a ‘Notify’ method for the reverse path. See Table 3 for more details.
The SPS server or client can request from a peer to stop data transmission over BLE by sending flow control values through the SPS_FLOW_CTRL characteristic. The flow control values are:
FLOW_ON0x01FLOW_OFF0x02
The recipient of the FLOW_OFF value must stop data transmission immediately. Transmission can resume when the value of FLOW_ON is received.
The client sends the flow control value via a GATT Write with no response message and the server sends a notification message.
The SPS client must enable notifications in the CCC attribute of SPS_SERVER_TX and SPS_FLOW_CTRL characteristics to activate the SPS device’s notifications for data exchange and flow control messages.
The configuration of the SPS application consists of two parts:
The Configuration Image
The Configuration Storage mechanism
Hint
The Configuration Image is the image in the flash that keeps the active configuration parameters.
The Configuration Storage mechanism will read from the flash and apply the active configuration parameters or will update them in the flash with the ones desired by the user.
The configuration header includes the following fields:
Signature: A “magic” number that identifies the configuration header.
Value: 0x70, 0x54.
Valid Flag: Denotes a valid image. The default value in the configuration
file should be 0xFF. The SPS application writes the Valid Flag (0xAA) value
in flash when an update is completed, or the mkimage application will do so
when a multi-image is built.
Structure ID: A counter increased by the application whenever the
configuration struct is updated and stored in an alternative bank.
Number of Items: The number of configuration elements in the configuration data.
CRC (Not Supported - For Future Use): A checksum calculated over the configuration data.
Version: Determines the configuration structure type and version, ensuring
the expected data are stored.
Data Size: The size of the configuration data (in bytes).
Encryption Flag (For Future Use): Indicates whether the configuration data
has been encrypted. Value 0x1 means data is encrypted, while 0x0 means data is
decrypted. The SPS application does not use this field currently, as encryption
is not supported.
In the multi-image, at least one of the Configuration Images must be populated and be valid, in order for the Configuration Storage mechanism to be activated.
The Element ID determines the semantics, type and maximum data size of the configuration data. A full list of the specified Element IDs and the corresponding info is available in Appendix A Configuration Parameters.
A configuration structure may contain any combination of different configuration fields. An Element ID should appear only once in a configuration structure. The actual data size in each element is determined by the element’s length.
The complete format of configuration structure is depicted below:
The Configuration Storage Mechanism serves several critical functions:
Reading Configuration Data from Flash: This mechanism is responsible for retrieving configuration data stored in non-volatile flash memory.
Applying Configuration Data: Once the configuration data is read, it is applied to the device, ensuring that the device operates with the correct settings.
Storing Updated Configuration Structures: When configuration updates are received from the Remote Configuration Service, the Configuration Storage Mechanism securely writes the new configuration structures back to the flash memory, ensuring persistent changes.
These operations are crucial for maintaining accurate device settings and seamless updates, making the Configuration Storage Mechanism a fundamental component of the system.
In the SPS application, Configuration Storage support is controlled by the definition CFG_CONFIG_STORAGE. The main functionality is implemented in file user_config_storage.c.
During boot, the Configuration Storage will read the Product Header to get the offset of the two Configuration Images. Then the headers are parsed to read the Valid Flag and the Structure ID flag. The selected Configuration Image is the one that has the Valid Flag 0xAA and the most updated Structure ID. In case that neither Configuration Image is valid, the application will use the hardcoded default values. Once a valid Configuration Image is found, the elements from that Configuration Image are read one by one. If an element is included in the application’s configuration structure, the corresponding Configuration value is updated, otherwise that element is ignored.
The Configuration Storage mechanism is also responsible saving new configuration values to the flash. These new configuration values are updated by the Remote Configuration Service. So, when the Remote Configuration Service updates a configuration parameter, the Configuration Storage is called. In every call, the Configuration Storage will save the whole Configuration Structure in the
offset of the Configuration image that is currently not used. So, at first, it will determine which Configuration Image position to use and then start to create the whole Configuration Image. It will save all the Configuration Data of the SPS’s Configuration Structure and then start to create the whole Header. First it will set the Valid Flag to Invalid (0xFF) and will keep it like this until all fields are updated. When everything is ready, it will increase the Structure Id by one and set the Valid Flag to 0xAA (Valid).
In this way, this Configuration Image will become the valid one to be used from now on.
The Remote Configuration Service is responsible to inform, update, save and apply the SPS application’s configuration parameters; and does that in real time.
Remote Configuration Service support is controlled by the definition CFG_PRF_REMOTE_CONFIG. The main functionality is implemented in the files remote_config.c, remote_config_task.c, user_remote_config.c and user_remote_config_task.c.
The Remote Configuration Service is supported only in the Device role, not the Host.
Table 5 Characteristics of the Device Configuration Service
Characteristic Name
Qualifier
Properties
Max Size (Bytes)
Configuration structure version
Mandatory
Read
66
Discover elements
Mandatory
Write/Notify
130
Write elements
Mandatory
Write/Notify
133
Read Element
Mandatory
Write/Notify
132
Configuration Structure Information
The configuration structure of the application consists of the following elements:
Configuration Structure Version: Identifies the type and version of the configuration structure of the application.
Discover Elements:
Max Number of Element IDs: The Remote configuration client writes in this characteristic the maximum number of element IDs that the server must include in the Discover response notification to trigger the discovery process. The server will respond with one or more Discover response notifications. The maximum number should not exceed 64.
Number of Elements: The server responds to the Discover elements command with one or more Discover responses sent through the same characteristic. The Number of Elements field denotes the number of elements included in the specific message. They should not exceed the maximum number requested by the remote configuration client.
More Messages: The More field denotes whether more messages are following. If it is 1, more Discover response messages will follow.
Auto-Adjustment for MTU: If the maximum number of element IDs creates responses that exceed the MTU size, it automatically decreases to the maximum value of allowed responses to be transmitted.
Element IDs: The element IDs follow in the message.
Figure 7 Notification Data Format in Discover Elements
Write elements:
The Remote configuration client writes the configuration data into this characteristic.
The data format is shown in following figure:
Figure 8 Write Configuration Data Format in Write Elements
Number of elements: Number of elements to be written in this message.
More: Set if more Write configuration messages will follow before the configuration is applied by the device. Cleared if this is the last message and the device must apply the configuration.
Payload: Sequence of elements. The number included in a single message depends on the size of the elements. The total size of an element’s data must not exceed 128 bytes.
The Remote configuration server will reply in a Write configuration process with a notification on the same characteristic. The response will be sent only when the ‘More’ field in the Write configuration command is clear (‘0x0’) and will include the following:
Figure 9 Notification Data Format in Write Elements Characteristic
If the write operation is completed successfully, the server will send a notification with Error code: 0x00 (No error). Then the Configuration Storage mechanism is called to save the new Configuration Structure to the flash. Afterwards, depending on the parameters that were updated, it may need to take some actions:
Connection related parameters: Run Parameters Update.
MTU size: Reset chip on the next disconnection, to apply the new MTU.
UART Baudrate: Reset chip immediately, to apply the new baudrate.*
In case the write operation is not completed successfully, the Element ID is the ID of the first element that the error in Error code is detected. If the error code is not related to any Element, then the reserved ‘0x0000’ ID will be used. The list of error codes is displayed in following table:
Error Code
Error
0x00
No error
0x01
Large element
0x02
Invalid number of elements
0x03
Unknown element ID
0x04
Invalid element length
0x05
Invalid element data
The Remote Configuration Server will do some basic data validation, before the updated configuration parameters are saved and applied. This is not done for all parameters. If validation fails, then a response with Error code: “Invalid element data” is generated.
If the number of elements is 0, or larger than the elements contained in the SPS application’s Configuration Structure, then a response with Error code: “Invalid number of elements” is generated.
If one of the element IDs is not included in the SPS application’s Configuration Structure, then a response with Error code: “Unknown element ID” is generated.
If the length of one of the elements is larger than the element’s max size, then a response with Error code: “Invalid element length” is generated.
During the whole write operation, if an error happens on any of the elements, then the element’s data will not be stored and applied.
Read Elements:
The Remote configuration client writes a parameter ID into this characteristic, and requests the command server to return the current values of the parameters.
The Remote configuration server sends a notification including the configuration data of a parameter, whenever the client requests it by writing the parameter ID to the read command characteristic.
The format of the notification data is shown in following Figure:
Figure 10 Indication Data Format in Read Elements Characteristic
If the read operation is completed successfully, the server will send a notification with Error code: 0x00 (No error) in the status field.
If the read operation is not completed successfully, it will send a notification where the status field will contain one of the Error codes of table :ref:`Error-table`. No Data will be sent in this case.
If the element ID is not included in the SPS application’s Configuration Structure, then a response with Error code: “Unknown element ID” is generated.
If the length of the element is larger than the notification’s maximum data allowed (128 bytes), then a response with Error code: “Invalid element length” is generated.
If the notification created is larger than the MTU size used, the Remote configuration server breaks the response into smaller fragments, according to the MTU size, and sends each of them as a separate notification response. All the notification responses will use “Large Response” as status, except the last one which will use “No Error”.
The SPS Configuration Structures for chips DA1453xand DA1458x, and both roles Device and Host, are presented in Table 17 and Table 18 and Table 19. These are the structures handled by the code.
The default values of the Configuration Structures, both for the Device role and the Host role are shown in Appendix B SPS Configuration Parameters. These values are hardcoded and will be used in case no valid Configuration Image is present in the flash.
The following section is a guide of how to change these hardcoded values in the code.
The configuration structure of the application includes the following parameters:
ELEM_ID_GAP_MTU:
Description: This parameter contains the MTU value to be used.
Location: It is located in the configuration structure user_gapm_conf in the file user_sps_device_config.c, within the member channel_map. The default value is initialized by definition DEFAULT_MTU. If changed by the Remote Configuration Service, the device will reset at the next disconnection.
Description: These parameters contain the minimum and maximum Connection Interval.
Location: They are located in the configuration structure user_connection_param_conf in the file user_sps_device_config.c, within the members intv_min and intv_max. The default values are initialized with hardcoded values. If changed by the Remote Configuration Service, the device will issue a Connection Parameters Request with the updated values.
ELEM_ID_CONN_LATENCY:
Description: This parameter contains the Connection Slave Latency.
Location: It is located in the configuration structure user_connection_param_conf in the file user_sps_device_config.c, within the member latency. The default value is initialized with a hardcoded value. If changed by the Remote Configuration Service, the device will issue a Connection Parameters Request with the updated value.
ELEM_ID_CONN_TIME_OUT:
Description: This parameter contains the Supervision Timeout.
Location: It is located in the configuration structure user_connection_param_conf in the file user_sps_device_config.c, within the member time_out. The default value is initialized with a hardcoded value. If changed by the Remote Configuration Service, the device will issue a Connection Parameters Request with the updated value.
ELEM_ID_USER_ADV_DATA:
Description: This parameter contains the Data of the Advertising frame.
Location: It is located in the configuration array user_advertise_data in the file user_sps_device_config.c. The default value is initialized with definition USER_ADVERTISE_DATA. If changed by the Remote Configuration Service, the new value is adopted immediately.
ELEM_ID_USER_ADV_DATA_LEN:
Description: This parameter contains the length of the Advertising Data.
Location: It is located in the configuration variable user_advertise_data_len in the file user_sps_device_config.c. The default value is initialized with definition USER_ADVERTISE_DATA_LEN. If changed by the Remote Configuration Service, the new value is adopted immediately.
ELEM_ID_PERIPH_UART_BAUDRATE:
Description: This parameter contains the UART’s baudrate.
Location: It is located in the configuration variable uart_baudrate_param in file user_sps_device_config.c. The default value is initialized with definition BAUDRATE_CONFIG. If changed by the Remote Configuration Service, the device will reset immediately.
The configuration structure of the application includes the following parameters:
ELEM_ID_CONN_CE_LEN_MIN, ELEM_ID_CONN_CE_LEN_MAX:
Description: These parameters contain the minimum and maximum Connection Event Duration.
Location: They are located in the configuration structure user_connection_param_conf in the file user_sps_host_config.c, within the members ce_len_min and ce_len_max. The default values are initialized with hardcoded values.
ELEM_ID_CENTRAL_CODE:
Description: This parameter contains the Operation of the device.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member code. The default value is initialized with an enumeration gapm_operation.
ELEM_ID_CENTRAL_SCAN_INTERVAL:
Description: This parameter contains the Scan Interval.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member scan_interval. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_SCAN_WINDOW:
Description: This parameter contains the Scan Window size.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member scan_window. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_PEER_ADDR_0:
Description: This parameter contains the Address of the first Client device to look for.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member peer_addr_0. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_PEER_ADDR_0_TYPE:
Description: This parameter contains the Type of the Address of the first Client device to look for.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c.
The configuration structure of the application includes the following parameters:
ELEM_ID_CONN_CE_LEN_MIN, ELEM_ID_CONN_CE_LEN_MAX:
Description: These parameters contain the minimum and maximum Connection Event Duration.
Location: They are located in the configuration structure user_connection_param_conf in the file user_sps_host_config.c, within the members ce_len_min and ce_len_max. The default values are initialized with hardcoded values.
ELEM_ID_CENTRAL_CODE:
Description: This parameter contains the Operation of the device.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member code. The default value is initialized with an enumeration gapm_operation.
ELEM_ID_CENTRAL_SCAN_INTERVAL:
Description: This parameter contains the Scan Interval.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member scan_interval. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_SCAN_WINDOW:
Description: This parameter contains the Scan Window size.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member scan_window. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_PEER_ADDR_0:
Description: This parameter contains the Address of the first Client device to look for.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c, within the member peer_addr_0. The default value is initialized with a hardcoded value.
ELEM_ID_CENTRAL_PEER_ADDR_0_TYPE:
Description: This parameter contains the Type of the Address of the first Client device to look for.
Location: It is located in the configuration structure user_central_conf in the file user_sps_host_config.c.
The SUOTA mechanism is used to update the application image in the device’s flash. After a successful update, this image becomes the active one. See reference document UM-B-119.
The SUOTA mechanism is upgraded to support configuration images as well. This way, the user can update the whole configuration structure without the need to change all parameters one by one. In the SUOTA mobile application the user selects the desired configuration image and updates the device. In the device, the SUOTA service, with the use of the image’s header, identifies that the new image is a configuration image and stores the new image to the suitable offset in the flash, overwrites in this way the configuration image that is not currently active.
If the new image is successfully stored, the SUOTA application makes this the active one.
