Libraries

ble-sht31-mt

Description

This library provides functions to handle Sensirion SHT31 Smart Gadget sensors via BLE interface. It requires the ble-con-manager-mt library.

It provides high level functions to establish connections to multiple sensors. This implies following workflow when using the library:

  • Add a SHT31Ble Smart Gadget sensor to the configuration
  • Initiate the connection to a previously added sensor
  • Read the measurement data from a sensor
  • Optionally enable automatic sending of measurement values from the sensor

OVERVIEW

Abstract:

This library provides functions to handle Sensirion SHT31 Smart Gadget sensors via BLE interface. It requires the ble-con-manager-mt library.

It provides high level functions to establish connections to multiple sensors. This implies the following workflow when using the library:

  • Add a SHT31Ble Smart Gadget sensor to the configuration (using SHT31Ble_Add())
  • Initiate the connection to a previously added sensor (using SHT31Ble_Connect())
  • Read the measurement data from a sensor (SHT31Ble_Measure())
  • Optionally enable automatic sending of measurement values from the sensor (SHT31Ble_EnableAutoMeasure())
How to use:
/* Software setup */ const { SCAN_TIMEOUT = 10, // Sensor scanning timeout SCAN_RETRY = 2, // Sensor scanning retries }; /* Global variables declarations */ static hSHT31_ble; // Handle for the SHT31 smart gadget /* App initialization */ #callback appInit() { new sSHT31Init[TSHT31BleInit] = [SHT31BLE_MODE_NEAREST, {0x00}, SCAN_RETRY, SCAN_TIMEOUT, 1000]; SHT31Ble_Init(BLEAPP_INTERFACE_FIRMWARE); // Initializes the SHT31Ble Smart Gadget library hSHT31_ble = SHT31Ble_Add(sSHT31Init); // Adds a SHT31Ble Smart Gadget sensor to the configuration SHT31Ble_Connect(hSHT31_ble); // Connect to the SHT31Ble Smart Gadget sensor #log("Connecting to a SHT31Ble Smart Gadget..."); } /* application entry point */ main() { salve( appInit); // Prepare device for the application start } /* SHT31Ble Smart Gadget library callback function */ SHT31Ble_EvtSensor(handle, iEvent, aData{}, iLen) { #pragma unused iLen switch(iEvent) { case SHT31BLE_EVT_NONE: #log("Sensor %d, SHT31BLE_EVT_NONE", handle); case SHT31BLE_EVT_CONNECTED: { #log("Sensor %d, SHT31BLE_EVT_CONNECTED", handle); SHT31Ble_EnableAutoMeasure(handle); // Enable automeasurement mode } case SHT31BLE_EVT_DISCONNECTED: #log("Sensor %d, SHT31BLE_EVT_DISCONNECTED", handle); case SHT31BLE_EVT_ERROR: { new iError = SHT31Ble_UnpackError(aData); // Unpack specific error #log("!Sensor %d, SHT31BLE_EVT_ERROR %d", handle, iError); } case SHT31BLE_EVT_CONF_DONE: #log("Sensor %d, SHT31BLE_EVT_CONF_DONE", handle); case SHT31BLE_EVT_DATA: { new aMeasurements[TSHT31Ble_SensorValues]; // Last sensor measurement values arrray aMeasurements = SHT31Ble_UnpackData(aData); // Unpack latest received measurement values #log("Sensor %d, SHT31BLE_EVT_DATA, SHT31: %.2f %%rH %.2f °C", handle, aMeasurements.fHumidity, aMeasurements.fTemperature); } } } /* Callback functions from ble-scanner-mt library */ BleConMngr_EvtConnected(iEvent, iIndex, sPeer[TBleConnMngrPeer]) { /* forward event to sensor lib(s) */ SHT31Ble_OnConnEvt(iEvent, iIndex, sPeer); } BleConMngr_EvtRead(iIndex, iCharHandle, iOffset, aData{}, iLen) { /* forward event to sensor lib(s) */ SHT31Ble_OnReadEvt(iIndex, iCharHandle, iOffset, aData, iLen); } BleConMngr_EvtReadResult(iIndex, iCharHandle, iResult) { /* forward event to sensor lib(s) */ SHT31Ble_OnReadResultEvt(iIndex, iCharHandle, iResult); } BleConMngr_EvtWriteResult(iIndex, iCharHandle, iResult, iLen) { /* forward event to sensor lib(s) */ SHT31Ble_OnWriteResultEvt(iIndex, iCharHandle, iResult, iLen); } BleConMngr_EvtNotify(iIndex, iCharHandle, aData{}, iLen) { /* forward event to sensor lib(s) */ SHT31Ble_OnNotifyEvt(iIndex, iCharHandle, aData, iLen); } BleConMngr_EvtError(iError) { #log("!BleConMngr_EvtError: %d", iError); // A (ble) error occured // add your application code }

REQUIRED

Callbacks:
This library requires the user to implement the following callback:
  • SHT31Ble_EvtSensor()

    • This library is based on the ble-con-manager-mt library which requires the user to implement a number of callbacks. These needs to be forwarded to the ble-sht31-mt specific library functions. Copy the following block to the main.p file of your project.

    BleConMngr_EvtConnected(iEvent, iIndex, sPeer[TBleConnMngrPeer]) { #log("~BleConMngr_EvtConnected: Event %d, Peer %d (%s - %02X:%02X:%02X:%02X:%02X:%02X, State: %d, Connhandle %d)", iEvent, iIndex, sPeer.aName, sPeer.aAddr{0}, sPeer.aAddr{1}, sPeer.aAddr{2}, sPeer.aAddr{3}, sPeer.aAddr{4}, sPeer.aAddr{5}, sPeer.iState, sPeer.iConnHandle) /* forward event to sensor lib(s) */ SHT31Ble_OnConnEvt(iEvent, iIndex, sPeer); } BleConMngr_EvtRead(iIndex, iCharHandle, iOffset, aData{}, iLen) { #log("~BleConMngr_EvtRead: Peer %d (Char: %d Offset: %d, Len: %d)", iIndex, iCharHandle, iOffset, iLen); /* forward event to sensor lib(s) */ SHT31Ble_OnReadEvt(iIndex, iCharHandle, iOffset, aData, iLen); } BleConMngr_EvtReadResult(iIndex, iCharHandle, iResult) { #log("~BleConMngr_EvtReadResult: Peer %d (Char: %d, iResult: %d)", iIndex, iCharHandle, iResult); /* forward event to sensor lib(s) */ SHT31Ble_OnReadResultEvt(iIndex, iCharHandle, iResult); } BleConMngr_EvtWriteResult(iIndex, iCharHandle, iResult, iLen) { #log("~BleConMngr_EvtWriteResult: Peer %d (Char: %d, iResult: %d, iLen: %d)", iIndex, iCharHandle, iResult, iLen); /* forward event to sensor lib(s) */ SHT31Ble_OnWriteResultEvt(iIndex, iCharHandle, iResult, iLen); } BleConMngr_EvtNotify(iIndex, iCharHandle, aData{}, iLen) { #log("~BleConMngr_EvtNotify: Peer %d (Char: %d, iLen: %d)", iIndex, iCharHandle, iLen); /* forward event to sensor lib(s) */ SHT31Ble_OnNotifyEvt(iIndex, iCharHandle, aData, iLen); } BleConMngr_EvtError(iError) { #log("!BleConMngr_EvtError: %d", iError); // a (ble) error occured // add your application code }
    SHT31Ble_EvtSensor(handle, iEvent, aData{}, iLen)

    Called every time when one of the following events happen:

  • The connection to a sensor could be established
  • The connection to a sensor has been disconnected (intentional disconnection)
  • An existing connection was interrupted (unintentional disconnection)
  • The sensor was not found (max number of retries exceeded)
  • An error occurred while establishing a connection
  • Measurement data received from the sensor is invalid
  • An error occured while writing data to the sensor
  • Automeasurement was successfully enabled
  • Valid measurement data received from the sensor

    • handle : s32 - Handle of a specific SHT31Ble Smart Gadget
    iEvent : SHT31BLE_EVT_X - Sensor events
    aData{} : u8 - Data buffer with available event data. Depends on the type of event
  • SHT31BLE_EVT_ERROR: call library function SHT31Ble_UnpackError()
  • SHT31BLE_EVT_DATA: call library function SHT31Ble_UnpackData()
    • iLen : s32 - Number of bytes available within data buffer

    BASIC

    SHT31BLE_MODE_X:

    Filter types used for scanning for a SHT31 Smart Gadget sensor

    SHT31BLE_MODE_NEAREST - (1) Filter for RSSI - use the sensor with the highest available RSSI.
    SHT31BLE_MODE_ADDR - (2) Filters for HW address.
    SHT31BLE_EVT_X:

    Sensor events

    SHT31BLE_EVT_CONNECTED - (1) Sensor connected event
    SHT31BLE_EVT_DISCONNECTED - (2) Sensor disconnected event
    SHT31BLE_EVT_ERROR - (3) Sensor error event
    SHT31BLE_EVT_CONF_DONE - (4) Sensor configuration done event
    SHT31BLE_EVT_DATA - (5) Sensor data event
    SHT31BLE_STATE_X:

    Sensor states

    SHT31BLE_STATE_ERROR - (-1) Sensor is in error state
    SHT31BLE_STATE_DISCONNECTED - (1) Sensor is in disconnected state
    SHT31BLE_STATE_CONNECTED - (2) Sensor is connected
    SHT31BLE_STATE_AM_ENABLE - (3) Enable automeasurement
    SHT31BLE_STATE_AM_ON - (4) Automeasurement is enabled
    SHT31BLE_ERROR_X:

    Sensor errors

    SHT31BLE_ERROR_CONLOST - (-2) The connection to a sensor is lost or an error occured while connecting to the sensor
    SHT31BLE_ERROR_NOTFOUND - (-3) The sensor was not found
    SHT31BLE_ERROR_READ - (-4) Error or Timeout has occurred while reading the data
    SHT31BLE_ERROR_WRITE - (-5) Error or Timeout has occurred while writing the data
    SHT31BLE_ERROR_NOTIFY - (-6) Received an unsupported notification from the sensor
    TSHT31BleInit:

    Configuration of a SHT31 Smart Gadget sensor

    iMode : SHT31BLE_MODE_X - Type of the filter that should be applied
    aAddr{} : u8 - HW address
  • Not required for SHT31BLE_MODE_NEAREST
  • For SHT31BLE_MODE_ADDR fill in the HW address of the sensor.
    • iScanRetries : u32 - Maximum number of rescans before BLE_CONMNGR_EVT_ERROR_NOTFOUND is issued.
    iScanInterval : u32 - Scan interval (in sec.) to be used when searching for the peer (If not set 10sec. is used).
    iConInterval : u32 - Connection interval (in ms) to be used when connecting to peer (If not set 1000ms. is used).
    TSHT31Ble_SensorValues:

    Structure holding the sensor measurement values

    fHumidity : Float - Measurement value for humidity
    fTemperature : Float - Measurement value for temperature
    SHT31Ble_Init(iInterface)

    Initializes the SHT31Ble Smart Gadget library

    iInterface : s32 - BLE Scanner App interface of the device that should be used (use BLEAPP_INTERFACE_x)
    returns : s32
    OK - If successful
    ERROR - If an error occurs
    SHT31Ble_Add(sInit[TSHT31BleInit])

    Adds a SHT31Ble Smart Gadget sensor configuration which will be used for the subsequent connection process (using SHT31Ble_Connect()).

    sInit : TSHT31BleInit - Configuration of a SHT31 Smart Gadget sensor
    returns : s32
    >= OK - SHT31Ble sensor handle, if successful
    ERROR - If one of the following errors occurs
  • If there is not enough free memory in the passed sensor configuration to add the filter
  • Unsupported filter mode (use SHT31BLE_MODE_X)
  • If all sensor slots are already in use (max. BLE_APP_MAX_CONNECTIONS)
    • SHT31Ble_Connect(handle)

    Initiates the connection to a previously added sensor

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget (Added by SHT31Ble_Add() )
    returns : s32
    BLE_CONMNGR_OK_OP_OMITTED - If sensor is already connected.
    OK - If command accepted
    ERROR - If invalid sensor handle provided.
    Command works in non-blocking mode. Callback function SHT31Ble_EvtSensor() is called when:
  • The connection to a sensor could be established
  • The connection to a sensor has been disconnected
  • An existing connection was interrupted (unintentional disconnection)
  • The sensor was not found (max number of retries exceeded)
  • An error occurred while establishing a connection
    • SHT31Ble_Measure(handle)

    Reads measurement data from a sensor

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    returns : s32
    OK - If command accepted
    ERROR - If invalid sensor handle provided.
    BLE_CONMNGR_ERROR_OP_INVALID - If reading is not possible in the current state (e.g sensor is not connected)
    Command works in non-blocking mode. Callback function SHT31Ble_EvtSensor() is called when all requested data has been received or if an error has occurred while reading the data.
    SHT31Ble_EnableAutoMeasure(handle)

    Enable automatic sending of measurements from the sensor

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    returns : s32
    OK - If command accepted
    ERROR - If one of the following errors occurs
  • Invalid sensor handle provided.
  • Sensor is not connected.
    • Command works in non-blocking mode. Callback function SHT31Ble_EvtSensor() is called every time valid measurement data is received from the sensor.
    SHT31Ble_Disconnect(handle)

    Initiates the disconnection from a sensor

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    returns : s32
    BLE_CONMNGR_OK_OP_OMITTED - If sensor is already disconnected.
    OK - If command accepted.
    ERROR - If invalid sensor handle provided.
    SHT31Ble_Remove(handle)

    Removes a previously added sensor from the configuration.

    If the sensor is connected, the connection is first disconnected. After that, the slot used for the sensor is released.
    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    returns : s32
    OK - If successful
    ERROR - If invalid sensor handle provided.
    SHT31Ble_GetState(handle)

    Gets the current sensor state

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    returns : SHT31BLE_STATE_X - Sensor states
    SHT31Ble_GetValues(handle, sSensorValues[TSHT31Ble_SensorValues])

    Gets the current measurement values

    handle : s32 - Sensor handle of a specific SHT31Ble Smart Gadget
    sSensorValues : TSHT31Ble_SensorValues - Structure holding the sensor measurement values
    returns : s32
    OK - If command accepted
    ERROR - If invalid sensor handle provided.
    SHT31Ble_Close()

    Closes the SHT31Ble Smart Gadget library

    returns : s32
    OK - If successful
    ERROR - If an error occurs
    SHT31Ble_UnpackError(data{})

    Extracts the information from a SHT31BLE_EVT_ERROR event response

    data{} : u8 - Data buffer from SHT31Ble_EvtSensor() callback
    returns : SHT31BLE_ERROR_X - Sensor errors
    SHT31Ble_UnpackData(data{})

    Extracts the information from a SHT31BLE_EVT_DATA event response

    data{} : u8 - Data buffer from SHT31Ble_EvtSensor() callback
    returns : TSHT31Ble_SensorValues - Structure holding the sensor measurement values

    EXPERT

    Debug Config:
    To configure debug mode add the following block to the main.dde file.
    /** --------------------------------------------------------------------------- * ble-sht31-mt: Debug Config * ----------------------------------------------------------------------------- * * Use this block to configure the debug mode: * * 0: No outputs * 1: Extended debug outputs via console outputs */ #define SHT31BLE_DEBUG 0

    On this page

    ble-sht31-mt

    GTCT | Imprint | Privacy Policy | Contact