Nordic Status Message Service (NSMS)

The Nordic Status Message Service (NSMS) is a custom service that provides the name of the status and a string describing the current status. The status can be either notified or directly read (without waiting for notification) to check the current status whenever the device is connected.

The NSMS service is used in the Bluetooth: Peripheral Status sample.

You can implement multiple instances of the service to show the status of different parts of the system. The client can distinguish different instances by the name provided in the Characteristic User Description (CUD).

Service UUID

The 128-bit vendor-specific service UUID is 57a70000-9350-11ed-a1eb-x0242ac120002.

Characteristics

This service has one characteristic with the Client Characteristic Configuration (CCC) and CUD descriptors. CUD holds the name of the Status Message and helps to distinguish between different instances of the NSMS on the same device.

Status Characteristic (57a70001-9350-11ed-a1eb-0242ac120002)

Notify

Enable notifications for the Status Characteristic to receive notifications when the status message changes.

Read

Read the current status.

Configuration

To use this library, enable the CONFIG_BT_NSMS Kconfig option.

API documentation

Header file: include/bluetooth/services/nsms.h
Source file: subsys/bluetooth/services/nsms.c
group bt_nsms

Nordic Status Message (NSMS) GATT Service API.

Defines

BT_UUID_NSMS_VAL

UUID of the NSMS Service.

BT_UUID_NSMS_STATUS_VAL

UUID of the Status characteristic.

BT_UUID_NSMS_SERVICE
BT_UUID_NSMS_STATUS
BT_NSMS_SECURITY_LEVEL_NONE
BT_NSMS_SECURITY_LEVEL_ENCRYPT
BT_NSMS_SECURITY_LEVEL_AUTHEN
BT_NSMS_SERVICE_DEF(_name, ...)
BT_NSMS_DEF(_nsms, _name, _slevel, _status_init, _len_max)

Create the Nordic Status Message Service instance.

This macro creates the Nordic Status Message Service instance and prepares it to work. Note that it allows to implement multiple instances and the only difference between them would be the name.

Parameters:

  • _nsms – Name of Status Message Service instance.

  • _name – NULL terminated string used as a CUD for Status Message Characteristic.

  • _slevel – Security level to use the characteristic.

    • BT_NSMS_SECURITY_LEVEL_AUTHEN - requires authentication

    • BT_NSMS_SECURITY_LEVEL_ENCRYPT - encryption is sufficient

    • BT_NSMS_SECURITY_LEVEL_NONE and other values - none

  • _status_init – Initial message.

  • _len_max – Maximal size of the message. The size of the message buffer.

Functions

ssize_t bt_nsms_status_read(struct bt_conn *conn, struct bt_gatt_attr const *attr, void *buf, uint16_t len, uint16_t offset)

Nordic Status Message Service reading command.

This is implementation used by BLE stack.

Note

Do not use it from the code.

int bt_nsms_set_status(const struct bt_nsms *nsms_obj, const char *status)

Set status.

This function sets status message and send notification to a connected peer, or all connected peers.

Parameters:

  • nsms_obj – [in] Pointer to Nordic Status Message instance.

  • status – [in] Pointer to a status string.

Return values:

0 – If the data is sent. Otherwise, a negative value is returned.

struct bt_nsms_status_str
#include <nsms.h>

The status.

Public Members

struct k_mutex *mtx

Data access mutex

size_t size

The size of the buffer

char *buf

Pointer to the buffer

struct bt_nsms
#include <nsms.h>

Nordic Status Message Service structure.

The structure that allows multi-instance implementation of the NSMS.

Public Members

const struct bt_gatt_attr *status_attr

Pointer to the status attribute