Wireless Connectivity Knowledge Base

cancel
Showing results for 
Search instead for 
Did you mean: 

Wireless Connectivity Knowledge Base

Knowledge Base Articles

I want to share with you the information that I found about Indication and notification. I hope this information help you to understand more about these topics. Indication and notifications are commands that could be send through the attribute(ATT) protocol. So, there are two roles defined at the ATT layer: Client devices access remote resources over a BLE link using the GATT protocol. Usually, the master is also the client but this is not required or mandatory. Server devices have the GATT database, access control methods, and provide resources to the remote client. Usually, the slave is also the server. BLE standard define two ways to transfer data for the server to the client: notification and indication. Maximum data payload size defined by the specification in each message is 20 bytes. Notifications and indications are initiated by the Server but enabled by the Client. Notification don't need acknowledged, so they are faster. Hence, server does not know if the message reach to the client. Indication need acknowledged to communicated. The client sent a confirmation message back to the server, this way server knows that message reached the client. One interesting thing defined by the ATT protocol is that a Server can't send two consecutive indications if the confirmation was not received. In other words, you have to wait for the confirmation of each indication in order to send the next indication. Figure 1. Indication/Notification Nevertheless, server are not able to send indications or notifications at the beginning of the communication. First, client must enable notifications and indications permissions on the server side, so, the server is allowed to send indications or notifications. This procedure involves the client to write the Client Characteristic Configuration Descriptor (CCCD) of the characteristic that will be notified/indicated. In other words, the client may request a notification for a particular characteristic from the server. Once the client enabled the notifications for such characteristic in the server, server can send the value to the client whenever it becomes available. For example, thinking in a heart rate sensor application connecting to Heart Rate smartphone application. Heart Rate Service can notify its Heart Rate Measurement Characteristic.  In this case, the sensor is the server while the smartphone is the client. Once devices are connected, smartphone application must set the notifications permissions of the Heart Rate Measurement Characteristic through its CCCD. Then, when smartphone application(client) set the CCCD withe notifications enabled, Heart Rate Sensor (server) is able to send notifications whenever a heart rate measurement is available. This same procedure is needed if the characteristic has indication properties.  At the end, the client is the one that allow the server to indicate or notify a characteristic. Finally, it is worth to comment that unlike notification, the indication is more reliable, but slower, because the server sends the data but the client must to confirm when data is received.
View full article
Overview Bluetooth Low Energy offers the ability to broadcast data in format of non-connectable advertising packets while not being in a connection. This GAP Advertisement is widely known as a beacon and is used in today’s IoT applications in different forms. This article will present the current beacon format in our demo application from the KW40Z software package and how to create the most popular beacon formats on the market. The advertising packet format and payload are declared in the gAppAdvertisingData structure from app_config.c. This structure points to an array of AD elements, advScanStruct: static const gapAdStructure_t advScanStruct[] = {   {     .length = NumberOfElements(adData0) + 1,     .adType = gAdFlags_c,     .aData = (void *)adData0   },    {     .length = NumberOfElements(adData1) + 1,     .adType = gAdManufacturerSpecificData_c,     .aData = (void *)adData1   } }; Due to the fact that all beacons use the advertising flags structure and that the advertising PDU is 31 bytes in length (Bluetooth Low Energy v4.1), the maximum payload length is 28 bytes, including length and type for the AD elements. The AD Flags element is declared as it follows: static const uint8_t adData0[1] =  { (gapAdTypeFlags_t)(gLeGeneralDiscoverableMode_c | gBrEdrNotSupported_c) }; The demo application uses a hash function to generate a random UUID for the KW40Z default beacon. This is done in BleApp_Init: void BleApp_Init(void) {     sha1Context_t ctx;         /* Initialize sha buffer with values from SIM_UID */     FLib_MemCopy32Unaligned(&ctx.buffer[0], SIM_UIDL);     FLib_MemCopy32Unaligned(&ctx.buffer[4], SIM_UIDML);     FLib_MemCopy32Unaligned(&ctx.buffer[8], SIM_UIDMH);     FLib_MemCopy32Unaligned(&ctx.buffer[12], 0);          SHA1_Hash(&ctx, ctx.buffer, 16);         /* Updated UUID value from advertising data with the hashed value */     FLib_MemCpy(&gAppAdvertisingData.aAdStructures[1].aData[3], ctx.hash, 16); } When implementing a constant beacon payload, please bear in mind to disable this code section. KW40Z Default Beacon The KW40Z software implements a proprietary beacon with the maximum ADV payload and uses the following Manufacturer Specific Advertising Data structure of 26 bytes. This is the default implementation of the beacon demo example from the KW40Z Connectivity Software package. static uint8_t adData1[26] = {     /* Company Identifier*/     0xFF, 0x01     /* Beacon Identifier */     0xBC,     /* UUID */                  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,                                   /* A */                     0x00, 0x00,     /* B */                     0x00, 0x00,     /* C */                     0x00, 0x00,     /* RSSI at 1m */            0x1E}; iBeacon iBeacon is a protocol designed by Apple. It uses a 20 byte payload that consists of the following identifying information [1] : To advertise an iBeacon packet, the user needs to change the second AD element, adData1, like below: static uint8_t adData1[25] = {                                0x4C, 0x00,                                   0x02, 0x15,         /* UUID */             0xD9, 0xB9, 0xEC, 0x1F, 0x39, 0x25, 0x43, 0xD0, 0x80, 0xA9, 0x1E, 0x39, 0xD4, 0xCE, 0xA9, 0x5C,         /* Major Version */    0x00, 0x01         /* Minor Version */    0x00, 0x0A,                                0xC5}; AltBeacon AltBeacon is an open specification designed for proximity beacon advertisements [2] . It also uses a Manufacturer Specific Advertising Data structure: To advertise an AltBeacon packet, the user needs to change the second AD element, like below: static uint8_t adData1[26] = {     /* MFG ID*/         0xFF, 0x01,     /* Beacon Code */   0xBE, 0xAC,     /* Beacon ID */     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04,     /* Ref RSSI*/       0xC5,     /* MFG RSVD*/       0x00}; Eddystone ™ Eddystone™ is an open Bluetooth® Smart beacon format from Google [3]. It offers three data type packets: Eddystone™-UID Eddystone™-URL Eddystone™-TLM Eddystone™ uses two advertising structures: Complete List of 16-bit Service UUIDs structure, which contains the Eddystone Service UUID (0xFEAA). Service Data structure, which also contains the Eddystone™ Service UUID (0xFEAA). Thus, advScanStruct will now have 3 elements: static const gapAdStructure_t advScanStruct[] = {   {     .length = NumberOfElements(adData0) + 1,     .adType = gAdFlags_c,     .aData = (void *)adData0   },    {     .length = NumberOfElements(adData1) + 1,     .adType = gAdComplete16bitServiceList_c,     .aData = (void *)adData1   },   {     .length = NumberOfElements(adData2) + 1,     .adType = gAdServiceData16bit_c,     .aData = (void *)adData2   } }; The complete List of 16-bit Service UUIDs element will look like: static const uint8_t adData1[2] =  { 0xAA, 0xFE }; Eddystone™-UID Eddystone™-UID broadcasts a unique 16-bit Beacon ID to identify a particular device in a group. The Service Data block has the following structure: To implement this, the user needs to add a third AD element, as follows: static uint8_t adData2[22] = {     /* ID */ 0xAA, 0xFE,     /* Frame Type */    0x00,     /* Ranging Data */  0xEE,     /* Namespace */     0x8B, 0x0C, 0xA7, 0x50, 0x09, 0x54, 0x77, 0xCB, 0x3E, 0x77,     /* Instance */      0x00, 0x00, 0x00, 0x00, 0x00, 0x01,     /* RFU */           0x00, 0x00}; Eddystone™-URL Eddystone™-URL broadcasts a compressed URL. The Service Data block has the following structure: In this example, we will implement a beacon which will advertise NXP’s webpage, http://www.nxp.com . To implement this, the user needs to add a third AD element, as follows: static const uint8_t adData2[9] = {     /* ID */ 0xAA, 0xFE,     /* Frame Type */    0x10,     /* TX Power */      0xEE,     /* URL scheme */    0x00,     /* Encode URL */    'n', 'x, 'p', 0x07}; Eddystone™-TLM Eddystone™-TLM broadcasts telemetry data about the beacon device operation. The Service Data block has the following structure: To implement this, the user needs to add a third AD element, as follows: static uint8_t adData2[16] = {     /* ID */ 0xAA, 0xFE,     /* Frame Type */    0x20,     /* TLM Version */   0x00,     /* VBATT */        0x00, 0x00,     /* TEMP */         0x00, 0x00,     /* ADV_CNT */      0x00, 0x00, 0x00, 0x00,     /* SEC_CNT */      0x00, 0x00, 0x00, 0x00};
View full article
One of the most difficult part of creating connected medical applications is, actually, keep it connected. Different protocols are available to transmit information from a medical device to a database or user interface. Sometimes integrating our application to the current communication protocols can be as difficult as developing the device itself. Freescale has launched its Bluetooth® Low Energy (BLE) chips, and with them, a complete software stack that integrates most of the available profiles for BLE oriented applications. Using this set, it becomes easy to integrate your current medical application to use BLE as communications method. Freescale Connectivity Software Examples The connectivity software includes examples to demonstrate BLE communications with a smartphone device. Using these examples as a base facilitates the integration with an existing application and reduces the required time it takes to have a fully connected application. This post uses as an example the Heart Rate Monitor demo to show how these applications can be customized. Modifying general device information The BLE services information reported by the device is stored in a file named “gatt_db.h”. This services information is what is shown on a smartphone when the device has connected. The Generic Access Profile service includes the device name reported when advertising. To change it just replace the device name between “” and update the character count. Detailed device information is accessed via the Device Information Service including the manufacturer name, model and serial number etcetera. This information can also be adjusted to the custom device requirements by modifying the string between “” and updating the character number. Adapting example code to report application data The connectivity software includes some predefined services that can be used to customize the server to report our application data. These predefined services already include structures with the information that needs to be reported to the client. On the application example file app.c some of these services are configured. For the heart rate service, a variable of type hrsConfig_t is created containing configuration information of the heart rate sensor such as the supported characteristics and sensor location. All of these characteristics are described in the heart rate service file heart_rate_interface.h /* Service Data*/ static basConfig_t      basServiceConfig = {service_battery, 0}; static disConfig_t      disServiceConfig = {service_device_info}; static hrsUserData_t    hrsUserData; static hrsConfig_t hrsServiceConfig = {service_heart_rate, TRUE, TRUE, TRUE, gHrs_BodySensorLocChest_c, &hrsUserData}; static uint16_t cpHandles[1] = { value_hr_ctrl_point }; /*! Heart Rate Service - Configuration */ typedef struct hrsConfig_tag {     uint16_t             serviceHandle;     bool_t               sensorContactSupported;     bool_t               sensorContactDetected;     bool_t               energyExpandedEnabled;     hrsBodySensorLoc_t   bodySensorLocation;     hrsUserData_t        *pUserData; } hrsConfig_t; This information is used to configure the server when the function BleApp_Config is called. /* Start services */ hrsServiceConfig.sensorContactDetected = mContactStatus; #if gHrs_EnableRRIntervalMeasurements_d    hrsServiceConfig.pUserData->pStoredRrIntervals = MEM_BufferAlloc(sizeof(uint16_t) * gHrs_NumOfRRIntervalsRecorded_c); #endif    Hrs_Start(&hrsServiceConfig); basServiceConfig.batteryLevel = BOARD_GetBatteryLevel(); Bas_Start(&basServiceConfig); /* Allocate application timers */ mAdvTimerId = TMR_AllocateTimer(); Once the server is configured, the application is stated by entering the device in advertising state in order to make it visible for clients. This is done by calling the function BleApp_Advertise that configures the server to start advertising. void BleApp_Start(void) { /* Device is not connected and not advertising*/ if (!mAdvState.advOn) { #if gBondingSupported_d if (mcBondedDevices > 0) { mAdvState.advType = fastWhiteListAdvState_c; } else { #endif mAdvState.advType = fastAdvState_c; #if gBondingSupported_d } #endif BleApp_Advertise(); } #if (cPWR_UsePowerDownMode)    PWR_ChangeDeepSleepMode(1); /* MCU=LLS3, LL=DSM, wakeup on GPIO/LL */ PWR_AllowDeviceToSleep(); #endif       } Once the server has been found and a connection has been stablished with the client, the configured services must be started. This is done by calling the “subscribe” function for each service. For heart rate sensor, the function Hrs_Suscribe must be called. This function is available from the heart_rate_interface files. /* Subscribe client*/ Bas_Subscribe(peerDeviceId);        Hrs_Subscribe(peerDeviceId); #if (!cPWR_UsePowerDownMode)  /* UI */            During connection, the application measurements can be reported to the client by using the “record measurement” functions included in the service interfaces. For the heart rate sensor this is the Hrs_RecordHeartRateMeasurement function. static void TimerMeasurementCallback(void * pParam) { uint16_t hr = BOARD_GetPotentiometerLevel(); hr = (hr * mHeartRateRange_c) >> 12; #if gHrs_EnableRRIntervalMeasurements_d    Hrs_RecordRRInterval(&hrsUserData, (hr & 0x0F)); Hrs_RecordRRInterval(&hrsUserData,(hr & 0xF0)); #endif if (mToggle16BitHeartRate) { Hrs_RecordHeartRateMeasurement(service_heart_rate, 0x0100 + (hr & 0xFF), &hrsUserData); } else { Hrs_RecordHeartRateMeasurement(service_heart_rate, mHeartRateLowerLimit_c + hr, &hrsUserData); } Hrs_AddExpendedEnergy(&hrsUserData, 100); #if (cPWR_UsePowerDownMode) PWR_SetDeepSleepTimeInMs(900); PWR_ChangeDeepSleepMode(6); PWR_AllowDeviceToSleep();    #endif } This updates the current measurement and sends a notification to the client indicating that a new measurement report is ready. Many profiles are implemented in the connectivity software to enable already developed medical applications with BLE connectivity. APIs are easy to use and can significantly reduce the development times.
View full article
This document describes how to add additional cluster to the router application in the AN12061-MKW41Z-AN-Zigbee-3-0-Base-Device Application Note.   The Router application's main endpoint contains Basic, Groups, Identify and OnOff server. The steps below describe how to add two clusters to Router: Temperature Measurement server and OnOff client. Note that these changes only go as far as making the new clusters added and discoverable, no functionality has been added to these clusters. Router/app_zcl_cfg.h The first step is to update the application ZCL Configuration file to add the new clusters (OnOff Client, Temperature Measurement Server) to the Router application endpoint. The HA profile already contains few clusters but Temperature Measurement cluster was added:   /* Profile 'HA' */ #define HA_ILLUMINANCEMEASUREMENT_CLUSTER_ID (0x0400) #define HA_DEFAULT_CLUSTER_ID                (0xffff) #define HA_OTA_CLUSTER_ID                    (0x0019) #define HA_TEMPMEASUREMENT_CLUSTER_ID        (0x0402) Router/app_zcl_globals.c The OnOff client was already present in Router endpoint but made discoverable and the Temperature Measurement cluster was added and made discoverable into Router application endpoint. The clusters are added  to   the Input cluster list (Server side) and output cluster list (Client side) and made discoverable using DiscFlag only for the cluster list for which it is enabled. So, assuming you need to add OnOff cluster client, you would need to use add the cluster id (0x0006 for OnOff) into input cluster list (Server side of cluster) and output cluster list (Client side of the cluster) and make it discoverable for output cluster list as it is a client cluster. For temperature measurement, you need to make it discoverable for input Cluster list as below: PRIVATE const uint16 s_au16Endpoint1InputClusterList[6] = { 0x0000, 0x0004, 0x0003, 0x0006, HA_TEMPMEASUREMENT_CLUSTER_ID , 0xffff, }; PRIVATE const PDUM_thAPdu s_ahEndpoint1InputClusterAPdus[6] = { apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, }; PRIVATE uint8 s_au8Endpoint1InputClusterDiscFlags[1] = { 0x1f }; PRIVATE const uint16 s_au16Endpoint1OutputClusterList[5] = { 0x0000, 0x0004, 0x0003, 0x0006, HA_TEMPMEASUREMENT_CLUSTER_ID , }; PRIVATE uint8 s_au8Endpoint1OutputClusterDiscFlags[1] = { 0x08 }; Now update Simple Descriptor structure (see the declaration of zps_tsAplAfSimpleDescCont and ZPS_tsAplAfSimpleDescriptor structures to understand how to correctly fill the various parameters) to reflect the input cluster and output cluster list correctly as below : PUBLIC zps_tsAplAfSimpleDescCont s_asSimpleDescConts[2] = { {    {       0x0000,       0,       0,       0,       84,       84,       s_au16Endpoint0InputClusterList,       s_au16Endpoint0OutputClusterList,       s_au8Endpoint0InputClusterDiscFlags,       s_au8Endpoint0OutputClusterDiscFlags,    },    s_ahEndpoint0InputClusterAPdus,    1 }, {    {       0x0104,       0,       1,       1,       6,       5,       s_au16Endpoint1InputClusterList,       s_au16Endpoint1OutputClusterList,       s_au8Endpoint1InputClusterDiscFlags,       s_au8Endpoint1OutputClusterDiscFlags,    },    s_ahEndpoint1InputClusterAPdus,    1 }, }; Router/zcl_options.h This file is used to set the options used by the ZCL. Enable Clusters The cluster functionality for the router endpoint was enabled: /****************************************************************************/ /*                             Enable Cluster                               */ /*                                                                          */ /* Add the following #define's to your zcl_options.h file to enable         */ /* cluster and their client or server instances                             */ /****************************************************************************/ #define CLD_BASIC #define BASIC_SERVER #define CLD_IDENTIFY #define IDENTIFY_SERVER #define CLD_GROUPS #define GROUPS_SERVER #define CLD_ONOFF #define ONOFF_SERVER #define ONOFF_CLIENT #define CLD_TEMPERATURE_MEASUREMENT #define TEMPERATURE_MEASUREMENT_SERVER Enable any optional Attributes and Commands for the clusters /****************************************************************************/ /* Temperature Measurement Cluster - Optional Attributes */ /* */ /* Add the following #define's to your zcl_options.h file to add optional */ /* attributes to the time cluster. */ /****************************************************************************/ #define CLD_TEMPMEAS_ATTR_TOLERANCE /****************************************************************************/ /* Basic Cluster - Optional Commands */ /* */ /* Add the following #define's to your zcl_options.h file to add optional */ /* commands to the basic cluster. */ /****************************************************************************/ #define CLD_BAS_CMD_RESET_TO_FACTORY_DEFAULTS /****************************************************************************/ /* OnOff Cluster - Optional Commands */ /* */ /* Add the following #define's to your zcl_options.h file to add optional */ /* commands to the OnOff cluster. */ /****************************************************************************/ #define CLD_ONOFF_CMD_OFF_WITH_EFFECT   Add the cluster creation and initialization into ZigBee Base device definitions The cluster functionality for some of the clusters (like OnOff Client) is already present on ZigBee Base Device. For Temperature Measurement cluster the functionality was added into ZigBee Base Device. <SDK>/middleware/wireless/Zigbee_3_0_6.0.6/core /ZCL/Devices/ZHA/Generic/Include/base_device.h The first step was including the Temperature Measurement header files into base device header file as shown below:   #ifdef CLD_TEMPERATURE_MEASUREMENT #include "TemperatureMeasurement.h" #endif The second step was adding cluster instance (tsZHA_BaseDeviceClusterInstances) into base device Instance as shown below: /* Temperature Measurement Instance */ #if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER) tsZCL_ClusterInstance sTemperatureMeasurementServer; #endif The next step was to define the cluster into the base device structure (tsZHA_BaseDevice) as below: #if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER) tsCLD_TemperatureMeasurement sTemperatureMeasurementServerCluster; #endif <SDK>/middleware/wireless/Zigbee_3_0_6.0.6/core / ZCL/Devices/ZHA/Generic/Include/base_device.c The cluster create function for Temperature Measurement cluster for server was called in ZigBee base device registration function:   #if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER)     /* Create an instance of a Temperature Measurement cluster as a server */    if(eCLD_TemperatureMeasurementCreateTemperatureMeasurement(&psDeviceInfo->sClusterInstance.sTemperatureMeasurementServer,                                                    TRUE,                                                    &sCLD_TemperatureMeasurement,                                                    &psDeviceInfo->sTemperatureMeasurementServerCluster,                                                    &au8TemperatureMeasurementAttributeControlBits[0]) != E_ZCL_SUCCESS)   {       return E_ZCL_FAIL;    } #endif Router/app_zcl_task.c Temperature Measurement Server Cluster Data Initialization - APP_vZCL_DeviceSpecific_Init() The default attribute values for the Temperature Measurement clusters are initialized: PRIVATE void APP_vZCL_DeviceSpecific_Init(void) {    sBaseDevice.sOnOffServerCluster.bOnOff = FALSE;     FLib_MemCpy (sBaseDevice.sBasicServerCluster.au8ManufacturerName, "NXP", CLD_BAS_MANUF_NAME_SIZE);     FLib_MemCpy (sBaseDevice.sBasicServerCluster.au8ModelIdentifier, "BDB-Router", CLD_BAS_MODEL_ID_SIZE);     FLib_MemCpy (sBaseDevice.sBasicServerCluster.au8DateCode, "20150212", CLD_BAS_DATE_SIZE);     FLib_MemCpy (sBaseDevice.sBasicServerCluster.au8SWBuildID, "1000-0001", CLD_BAS_SW_BUILD_SIZE);    sBaseDevice.sTemperatureMeasurementServerCluster.i16MeasuredValue = 0;    sBaseDevice.sTemperatureMeasurementServerCluster.i16MinMeasuredValue = 0;    sBaseDevice.sTemperatureMeasurementServerCluster.i16MaxMeasuredValue = 0; }
View full article
I was investigating about how to create a current profile and I found interesting information I would like to share with the community. So, I decided to create an example to accomplish this task using BLE stack included in the MKW40Z Connectivity Software package. The demo to create is an Humidity Collector which make use of the Humidity custom profile and is based on the Temperature Collector demonstration application. The first thing to know is that the Generic Attribute Profile (GATT) establishes in detail how to exchange all profile and user data over a BLE connection. GATT deals only with actual data transfer procedures and formats. All standard BLE profiles are based on GATT and must comply with it to operate correctly. This makes GATT a key section of the BLE specification, because every single item of data relevant to applications and users must be formatted, packed, and sent according to the rules.                                      GATT defines two roles: Server and Client. The GATT server stores the data transported over the Attribute Protocol (ATT) and accepts Attribute Protocol requests, commands and confirmations from the GATT client. The GATT client accesses data on the remote GATT server via read, write, notify, or indicate operations. Notify and indicate operations are enabled by the client but initiated by the server, providing a way to push data to the client. Notifications are unacknowledged, while indications are acknowledged. Notifications are therefore faster, but less reliable. Figure 1. GATT Client-Server      GATT Database establishes a hierarchy to organize attributes. These are the Profile, Service, Characteristic and Descriptor. Profiles are high level definitions that define how services can be used to enable an application and Services are collections of characteristics. Descriptors defined attributes that describe a characteristic value. To define a GATT Database several macros are provided by the GATT_DB API in the Freescale BLE Stack, which is part KW40Z Connectivity Software package. Figure 2. GATT database      To know if the Profile or service is already defined in the specification, you have to look for in Bluetooth SIG profiles and check in the ble_sig_defines.h file if this is already declared in the code. In our case, the service is not declared, but the characteristic of the humidity is declared in the specification. Then, we need to check if the characteristic is already included in ble_sig_defines.h. Since, the characteristic is not included, we need to define it as shown next: /*! Humidity Charactristic UUID */ #define gBleSig_Humidity_d                      0x2A6F      The Humidity Collector is going to have the GATT client; this is the device that will receive all information from  the GATT server. Demo provided in this post works like the Temperature Collector. When the Collector enables the notifications from the sensor, received notifications will be printed in the serial terminal. In order to create the demo we need to define or develop a service that has to be the same as in the GATT Server, this is declared in the gatt_uuid128.h.If the new service is not the same, they will never be able to communicate each other. All macros function or structures in BLE stack of KW40Z Connectivity Software have a common template. Hence, we need to define this service in the gatt_uuid128.h as shown next: /* Humidity */ UUID128(uuid_service_humidity, 0xfe ,0x34 ,0x9b ,0x5f ,0x80 ,0x00 ,0x00 ,0x80 ,0x00 ,0x10 ,0x00 ,0x02 ,0x00 ,0xfa ,0x10 ,0x10)      During the scanning process is when the client is going to connect with the Server. Hence, function CheckScanEvent can help us to ensure that peer device or server device support the specified service, in this case, it will be the humidity service we just created in the previous step. Then, CheckScanEvent needs to check which device is on advertising mode and with MatchDataInAdvElementList to verify if it is the same uuid_service_humidity , i f the service is not in the list, client is not going to connect. CheckScanEvent function should look as shown next: static bool_t CheckScanEvent(gapScannedDevice_t* pData) { uint8_t index = 0; uint8_t name[10]; uint8_t nameLength; bool_t foundMatch = FALSE; while (index < pData->dataLength) {         gapAdStructure_t adElement;                 adElement.length = pData->data[index];         adElement.adType = (gapAdType_t)pData->data[index + 1];         adElement.aData = &pData->data[index + 2];          /* Search for Humidity Custom Service */         if ((adElement.adType == gAdIncomplete128bitServiceList_c) ||           (adElement.adType == gAdComplete128bitServiceList_c))         {             foundMatch = MatchDataInAdvElementList(&adElement, &uuid_service_humidity, 16);         }                 if ((adElement.adType == gAdShortenedLocalName_c) ||           (adElement.adType == gAdCompleteLocalName_c))         {             nameLength = MIN(adElement.length, 10);             FLib_MemCpy(name, adElement.aData, nameLength);         }                 /* Move on to the next AD elemnt type */         index += adElement.length + sizeof(uint8_t); } if (foundMatch) {         /* UI */         shell_write("\r\nFound device: \r\n");         shell_writeN((char*)name, nameLength-1);         SHELL_NEWLINE();         shell_writeHex(pData->aAddress, 6); } return foundMatch; } The humidity_interface.h file should define the client structure and the server structure. For this demo, we only need the client structure, however, both are defined for reference. The Client Structure has all the data of the Humidity Service, in this case is a Service, characteristic, descriptor and CCCD handle and the format of the value. /*! Humidity Client - Configuration */ typedef struct humcConfig_tag { uint16_t    hService; uint16_t    hHumidity; uint16_t    hHumCccd; uint16_t    hHumDesc; gattDbCharPresFormat_t  humFormat; } humcConfig_t; The next configuration structure is for the Server; in this case we don’t need it. /*! Humidity Service - Configuration */ typedef struct humsConfig_tag { uint16_t    serviceHandle; int16_t     initialHumidity;        } humsConfig_t;     Now that the Client Structure is declared, go to the app.c and modify some functions. There are functions that help to store all the data of the humidity service. In our case they are 3 functions for the service, characteristic and descriptor. You have to be sure that the service that you create and the characteristics of humidity are in the functions. The Handle of each data is stored in the structure of the client. The three functions that need to be modify are the next: BleApp_StoreServiceHandles() stores handles for the specified service and characteristic. static void BleApp_StoreServiceHandles (     gattService_t   *pService ) {     uint8_t i;           if ((pService->uuidType == gBleUuidType128_c) &&         FLib_MemCmp(pService->uuid.uuid128, uuid_service_humidity, 16))     {         /* Found Humidity Service */         mPeerInformation.customInfo.humClientConfig.hService = pService->startHandle;                 for (i = 0; i < pService->cNumCharacteristics; i++)         {             if ((pService->aCharacteristics[i].value.uuidType == gBleUuidType16_c) &&                 (pService->aCharacteristics[i].value.uuid.uuid16 == gBleSig_Humidity_d))             {                 /* Found Humidity Char */                 mPeerInformation.customInfo.humClientConfig.hHumidity = pService->aCharacteristics[i].value.handle;             }         }     } } BleApp_StoreCharHandles() handles the descriptors. static void BleApp_StoreCharHandles (     gattCharacteristic_t   *pChar ) {     uint8_t i;         if ((pChar->value.uuidType == gBleUuidType16_c) &&         (pChar->value.uuid.uuid16 == gBleSig_Humidity_d))     {            for (i = 0; i < pChar->cNumDescriptors; i++)         {             if (pChar->aDescriptors[i].uuidType == gBleUuidType16_c)             {                 switch (pChar->aDescriptors[i].uuid.uuid16)                 {                     case gBleSig_CharPresFormatDescriptor_d:                     {                         mPeerInformation.customInfo.humClientConfig.hHumDesc = pChar->aDescriptors[i].handle;                         break;                     }                     case gBleSig_CCCD_d:                     {                         mPeerInformation.customInfo.humClientConfig.hHumCccd = pChar->aDescriptors[i].handle;                         break;                     }                     default:                         break;                 }             }         }     } } BleApp_StoreDescValues() stores the format of the value. static void BleApp_StoreDescValues (     gattAttribute_t     *pDesc ) {     if (pDesc->handle == mPeerInformation.customInfo.humClientConfig.hHumDesc)     {         /* Store Humidity format*/         FLib_MemCpy(&mPeerInformation.customInfo.humClientConfig.humFormat,                     pDesc->paValue,                     pDesc->valueLength);     }   }      After we s tore all the data of the Humidity Service, we need to check the notification callback. Every time the Client receives a notification with the BleApp_GattNotificationCallback(),  call the BleApp_PrintHumidity() function and check the Format Value ; in this case is 0x27AD  that mean percentage and also have to be the same on the GATT server. static void BleApp_GattNotificationCallback (     deviceId_t serverDeviceId,     uint16_t characteristicValueHandle,     uint8_t* aValue,     uint16_t valueLength ) { /*Compare if the characteristics handle Server is the same of the GATT Server*/     if (characteristicValueHandle == mPeerInformation.customInfo.humClientConfig.hHumidity)     {            BleApp_PrintTemperature(*(uint16_t*)aValue);     }  } BleApp_PrintHumidity() print the value of the Humidity, but first check if the format value is the same. static void BleApp_PrintHumidity (     uint16_t humidity ) {     shell_write("Humidity: ");     shell_writeDec(humidity);      /*If the format value is the same, print the value*/     if (mPeerInformation.customInfo.humClientConfig.humFormat.unitUuid16 == 0x27AD)     {         shell_write(" %\r\n");     }     else     {         shell_write("\r\n");     } } Step to include the file to the demo. 1. Create a clone of the Temperature_Collector with the name of Humidity_Collector 2. Unzip the Humidity_Collector.zip file attached to this post. 3. S ave the humidity folder i n the fallowing path: < kw40zConnSoft _install_dir> \ConnSw\bluetooth\profiles . 4. R eplaces the common folder in the next path: < kw40zConnSoft _install_dir> \ConnSw\examples\bluetooth\humidity_sensor\common . Once you already save the folders in the corresponding path you must to indicate in the demo where they are and drag the file in the humidity folder to the workspace. For test the demo fallow the next steps: Compile the project and run. Press SW1 for the advertising/scanning mode, and wait to connect it. Once the connection finish, press the SW1 of the Humidity Sensor board to get and print the data. Enjoy the demo! NOTE : This demo works with the Humidity Sensor demo. This means that you need one board programmed with the Humidity Sensor application and a second board with the Humidity Collector explained in this post. Figure 3. Example of the Humidity Collector using the Humidity Sensor.
View full article
Overview The Bluetooth specification defines 4 Generic Access Profile (GAP) roles for devices operating over a Low Energy physical transport [1]: Peripheral Central Broadcaster Observer The Bluetooth Low Energy Host Stack implementation on the Kinetis KW40Z offers devices the possibility to change between any of the 4 roles at run time. This article will present the interaction with the Bluetooth Low Energy Host API needed to implement a GAP multiple role device. General Procedure instructions Running the GAP roles requires the application to go through the following 3 steps: Configuration - Stack configuration for the desired GAP role The application needs to configure the stack parameters, e.g. advertising parameters, advertising data, scan parameters, callbacks. Note that configuration of the advertising parameters or scanning response and advertising data can be done only once if the values don’t change at runtime. The configuration is always made in the Link Layer Standby state. Start - Running the role The application needs to start advertising, scanning or initiate connection. Stop - Return to Standby state When changing between roles, the Link layer must always go through the Link Layer Standby state. Running as a GAP Broadcaster or GAP Peripheral The GAP Broadcaster or Peripheral sends advertising events. Additionally, the GAP Peripheral will accept the establishment of a LE link. This is why the GAP Observer will only support the Non Connectable Advertising mode (gAdvNonConnectable_c). Both roles requires configuration of advertising data, advertising parameters. The configuration (gAppAdvertisingData, gAppScanRspData and gAdvParams) usually resides in app_config.c. The confirmation events for setting these parameters is received in BleApp_GenericCallback. The confirmation event for the changing state of advertising is received in BleApp_AdvertisingCallback. Configuration /* Setup Advertising and scanning data */ Gap_SetAdvertisingData(&gAppAdvertisingData, &gAppScanRspData); /* Setting only for GAP Broadcaster role */ gAdvParams. advertisingType = gAdvNonConnectable_c; /* Set advertising parameters*/ Gap_SetAdvertisingParameters(&gAdvParams); Start App_StartAdvertising(BleApp_AdvertisingCallback, BleApp_ConnectionCallback); Stop Gap_StopAdvertising(); Running as a GAP Observer The GAP Observer receives advertising events. Unlike the GAP Peripheral or Broadcaster, it does not need to set scanning parameters separately. It passes the configuration with the start procedure. The configuration (gAppScanParams) usually resides in app_config.c. The confirmation event for the changing state of scanning is received in BleApp_ScanningCallback. Configuration and Start App_StartScanning(&gAppScanParams, BleApp_ScanningCallback); Stop Gap_StopScanning (); Running as a GAP Central The GAP Central initiates the establishment of the LE link. Like the GAP Observer, it passes the configuration with the start procedure. The configuration (gConnReqParams) usually resides in app_config.c. The confirmation event for the changing state of link is received in BleApp_ConnectionCallback. Configuration and Start Gap_Connect(&gConnReqParams, BleApp_ConnectionCallback); Stop Gap_Disconnect(deviceId); Example An out-of-the box example for multiple role is attached. The application named blood_pressure_multi_role implements a Blood Pressure GATT client and server and can switch between the following GAP roles: Peripheral, Observer and Central. The contents of the archive needs to be copied to the following location: <Installer Path>\KW40Z_Connectivity_Software_1.0.1\ConnSw\examples\bluetooth\ The application can be found at: <Install Path specified>\KW40Z_Connectivity_Software_1.0.1\ConnSw\examples\bluetooth\blood_pressure_multi_role\frdmkw40z\bare_metal\build\iar\blood_pressure_multi_role.eww Running as GAP Peripheral Press SW4. LED1 will start flashing and the console will show that the Link Layer enters Advertising. If the Link Layer was in a previous state, it will go through Standby. static void BleApp_Advertise(void) {     /* Ensure Link Layer is in Standby */     BleApp_GoToStandby();         shell_write(" GAP Role: Peripheral\n\r");     mGapRole = gGapPeripheral_c;         /* Start GAP Peripheral */     App_StartAdvertising(BleApp_AdvertisingCallback, BleApp_ConnectionCallback); } Running as GAP Observer Press SW3. A chasing LED pattern will start and the console will show that the Link Layer enters Scanning. If the Link Layer was in a previous state, it will go through Standby. static void BleApp_Scan(void) {     /* Ensure Link Layer is in Standby */     BleApp_GoToStandby();         shell_write(" GAP Role: Observer\n\r");     mGapRole = gGapObserver_c;         /* Start GAP Observer */     App_StartScanning(&gAppScanParams, BleApp_ScanningCallback); } Running as GAP Central If the Link Layer is in scanning and finds a Blood Pressure Sensor, it will go through Standby and initiate connection. static void BleApp_Connect(void) {     /* Ensure Link Layer is in Standby */     BleApp_GoToStandby();         shell_write(" GAP Role: Central\n\r");     mGapRole = gGapCentral_c;         /* Start GAP Central */     Gap_Connect(&gConnReqParams, BleApp_ConnectionCallback); } Returning to Standby Pressing SW3 for more than 2 seconds, brings the Link Layer back in Standby. static void BleApp_GoToStandby(void) {     /* Check if connection is on */     if (mPeerInformation.deviceId != gInvalidDeviceId_c)     {         /* Stop GAP Central or Peripheral */         Gap_Disconnect(mPeerInformation.deviceId);     }     if (mAdvOn)     {         /* Stop GAP Peripheral or Bradcaster */         Gap_StopAdvertising();     }         if (mScanningOn)     {         /* Stop GAP Observer */         Gap_StopScanning();     } } References [1] BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part C], 2.2 PROFILE ROLES
View full article
When developing portable applications using batteries, it is important to keep track of the remaining battery level to inform the user and take action when it drops to a level that might be critical for the correct device functionality. A common measurement method consists of taking a sample of the current battery voltage and correlate it to a percentage depending on its capacity. Then this value is reported to the user in a visual manner. MKW40 is a system on chip (SoC) that embeds a processor and a Bluetooth® Low Energy (BLE)/802.15.4 radio for wireless communications. This posts describes how to obtain the current battery level and report it via BLE using this part. Hardware considerations Typically, the battery voltage is regulated so the MCU has a stable power supply across the whole battery life. This causes the ADC supply voltage to be lower than the actual battery voltage. To address this, a voltage divider is used to adequate the battery voltage to levels that can be read by the ADC. Figure 1 Typical battery level divider circuit The MKW40 includes a voltage divider on its embedded DC-DC converter removing the need to add this voltage divider externally. It is internally connected to the ADC0 channel 23 so reading this channel obtains the current level of the power source connected to the DC-DC converter in. Figure 2 DC-DC converter with battery voltage monitor Software implementation Software implementation consists in acquiring the ADC value, correlate it with a percentage level and transmit it using BLE. The connectivity software includes functions to perform all those actions. A voltage divider connected to the battery and internally wired to an ADC channel is embedded in the SoC. For the MKW40Z it is the ADC0 single ended channel 23 (ADC0_CH23) . There are some examples in the Kinetis Software Development Kit (KSDK) documentation explaining how to configure the ADC module. The connectivity software includes a function named BOARD_InitAdc in the file app.c where this is initialized. void BleApp_Init(void) {     /* Initialize application support for drivers */     BOARD_InitAdc(); <-- Initialization function         /* Initialize Software-timer */     SwTimer_Init();           /* Status Indicator fade initialization */     status_indicator_fade_init();     /* Initialise ECG Acquisition system */     ecg_acquisition_init();     /* Initialize battery charger pin configuration */     power_manager_init();     /* Create Advertising Timer */     advertisingTimerId = SwTimer_CreateTimer(TimerAdvertisingCallback); } Once initialized, this ADC channel must be read to obtain the current voltage present in the divisor. There are also some cool examples in the KSDK documentation on how to do this. The obtained value is a digital representation of the voltage in the divisor and is relative to the VDDA or VREFH voltage (depending on what is used as reference for the ADC). Since the battery voltage varies over the time (unless you use a voltage regulator or use the DC-DC converter in buck mode), the most accurate way to get the battery voltage is to obtain the actual voltage that is referencing the ADC first. For this, the MKW40Z includes a 1V reference voltage channel wired to another ADC channel: ADC0_CH27. Reading this ADC channel obtains the number of counts that correspond to 1V, and VREF can be calculated using the next formula. Once the VRef voltage has been obtained, it is possible to determine the voltage present in the battery voltage divisor by using the following formula. The obtained voltage is still only a portion of the actual battery voltage. To obtain the full voltage, the obtained value must be multiplied by the divisor relation. This relation is selected in the DC-DC register DCDC_REG0:DCDC_VBAT_DIV_CTRL and can be: VBATT, VBATT/2 or VBATT/4. After the full VBAT voltage is obtained, it must be correlated to a percentage depending on the values set for 0% and 100%. Using the slope method is a good approach to correlate the voltage value. For this, the slope m must be calculated using the formula. Where V100% is the voltage in the battery when it is fully charged, and V0% is the voltage in the battery when it is empty. Once m has been calculated, the battery percentage can be obtained using the formula: The Connectivity Software includes a function that obtains the current battery voltage connected to the DC-DC input and returns the battery percentage. It is included in the board.c file. uint8_t BOARD_GetBatteryLevel(void) {     uint16_t batVal, bgVal, batLvl, batVolt, bgVolt = 100; /*cV*/         bgVal = ADC16_BgLvl();     DCDC_AdjustVbatDiv4(); /* Bat voltage  divided by 4 */     batVal = ADC16_BatLvl() * 4; /* Need to multiply the value by 4 because the measured voltage is divided by 4*/         batVolt = bgVolt * batVal / bgVal;         batLvl = (batVolt - MIN_VOLT_BUCK) * (FULL_BAT - EMPTY_BAT) / (MAX_VOLT_BUCK - MIN_VOLT_BUCK);     return ((batLvl <= 100) ? batLvl:100);    } Reporting battery level After the battery level has been determined it can be now reported via BLE. The Connectivity Software includes predefined profile files to be included in custom applications. Battery profile is included in the files battery_service.c and .h, under the Bluetooth folder structure. To make use of them, make sure that they are included in your project. Then, include the file battery_interface.h in your BLE application file. An example using the included BLE applications is shown. In app.c (Connectivity Software examples application file) include the battery service interface #include "battery_interface.h" In the variable declaration section, create a new basConfig_t variable. This is needed to configure a new service. static basConfig_t      basServiceConfig = {service_battery, 0}; The new service needs to be created after the BLE stack has been initialized. When this happens, the function BleApp_Config is executed. Inside this function, the battery service is started.    /* Start services */ hrsServiceConfig.sensorContactDetected = mContactStatus; #if gHrs_EnableRRIntervalMeasurements_d    hrsServiceConfig.pUserData->pStoredRrIntervals = MEM_BufferAlloc(sizeof(uint16_t) * gHrs_NumOfRRIntervalsRecorded_c); #endif    Hrs_Start(&hrsServiceConfig);     Bas_Start(&basServiceConfig);         /* Allocate application timers */     mAdvTimerId = TMR_AllocateTimer(); mMeasurementTimerId = TMR_AllocateTimer(); mBatteryMeasurementTimerId = TMR_AllocateTimer(); Function Bas_Start is used for this purpose. This function starts the battery service functionality indicating that it needs to be reported by the BLE application. After a central has successfully connected to the peripheral device, the battery service must be subscribed so it’ measurements can be reported to the central. For this, the function Bas_Suscribe is used inside the connection callback. Following code shows its implementation in the connectivity software. It takes place in the connection callback function BleApp_ConnectionCallback in app.c switch (pConnectionEvent->eventType) {         case gConnEvtConnected_c:         {             mPeerDeviceId = peerDeviceId;             /* Advertising stops when connected */             mAdvState.advOn = FALSE; #if gBondingSupported_d                /* Copy peer device address information */             mPeerDeviceAddressType = pConnectionEvent->eventData.connectedEvent.peerAddressType;             FLib_MemCpy(maPeerDeviceAddress, pConnectionEvent->eventData.connectedEvent.peerAddress, sizeof(bleDeviceAddress_t)); #endif  #if gUseServiceSecurity_d                        {                 bool_t isBonded = FALSE ;                                if (gBleSuccess_c == Gap_CheckIfBonded(peerDeviceId, &isBonded) &&                     FALSE == isBonded)                 { Gap_SendSlaveSecurityRequest(peerDeviceId, TRUE, gSecurityMode_1_Level_3_c);                 }             } #endif                        /* Subscribe client*/             Bas_Subscribe(peerDeviceId);                     Hrs_Subscribe(peerDeviceId);                                                         /* UI */                        LED_StopFlashingAllLeds();                         /* Stop Advertising Timer*/             mAdvState.advOn = FALSE;             TMR_StopTimer(mAdvTimerId);                        /* Start measurements */ TMR_StartLowPowerTimer(mMeasurementTimerId, gTmrLowPowerIntervalMillisTimer_c, TmrSeconds(mHeartRateReportInterval_c), TimerMeasurementCallback, NULL);               } Once the service has been subscribed, a new measurements can be registered by using the Bas_RecordBatteryMeasurement function at any time. Bas_RecordBatteryMeasurement(basServiceConfig.serviceHandle, basServiceConfig.batteryLevel); This function receives the battery service handler previously defined (static basConfig_t basServiceConfig = {service_battery, 0}) and the current battery level percentage as input parameters. When a disconnection occurs, the battery service must be unsubscribed so no further updates are performed during disconnection. For this, the Bas_Unsuscribe function must be used after a disconnection event. case gConnEvtDisconnected_c:         {             /* Unsubscribe client */             Bas_Unsubscribe();             Hrs_Unsubscribe();             mPeerDeviceId = gInvalidDeviceId_c; Now, updated battery levels can be reported by the BLE device letting the user know when a battery must be replaced or recharged.
View full article
If the application running in the KW41Z does not operate in low power mode, the device could work without the 32 kHz oscillator. However, for it to work correctly, the clock configuration must be changed. Figure 1.  KW41Z clock distribution By default, the software stack running on the KW41Z selects a clock source that requires the 32 kHz oscillator. However, if the 32 kHz oscillator is not available, the clock configuration must be changed. Fortunately, the option to change it is already implemented, it is only required to change the clock configuration to the desired one. To do this, change the value for the CLOCK_INIT_CONFIG macro located in the app_preinclude.h file. /* Define Clock Configuration */ #define CLOCK_INIT_CONFIG           CLOCK_RUN_32‍‍‍‍‍‍‍‍ ‍ ‍ In the selected mode in this example, CLOCK_RUN_32, the selected clock mode is BLPE (Bypassed Low Power External). In this mode, the FLL is bypassed entirely, and clock is derived from the external RF oscillator, in this case, the 32 MHz external clock. These macros are the default available options to change the clock configuration, they are located in the board.h file. It is up to the application and the developer to chose the most appropriate configuration. #define CLOCK_VLPR       1U #define CLOCK_RUN_16     2U #define CLOCK_RUN_32     3U #define CLOCK_RUN_13     4U #define CLOCK_RUN_26     5U #define CLOCK_RUN_48_24  6U #define CLOCK_RUN_48_16  7U #define CLOCK_RUN_20_FLL 8U‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ More information regarding the different clock modes and their clock sources are available in the KW41Z reference manual, Chapter 5: Clock Distribution, section 5.4 Clock definitions, and Chapter 24: Multipurpose Clock Generator.
View full article
The Thread Low Power End Device is preconfigured to have both the MCU in low power state and the radio turned off most of the time to preserve battery life. The device wakes up periodically and polls its parent router for data addressed to it or optionally initiates sending data to the network by means of the parent router. The low-power module (LPM) from the connectivity framework simplifies the process of putting a Kinetis-based wireless network node into the low-power or sleep modes. For the MKW41Z there are six low-power modes available. By default, the Thread Low Power End Device uses Deep sleep mode 3, where: MCU in LLS3 mode. Link layers remain idle. RAM is retained. The wake-up sources are: GPIO (push buttons). DCDC power switch (In buck mode). LPTMR with the 32kHz oscillator as clock source. The LPTMR timer is also used to measure the time that the MCU spends in deep sleep to synchronize low-power timers at wake-up. See the Connectivity Framework Reference Manual and PWR_Configuration.h for more information about the sleep deep modes. To change the polling time on deep sleep mode 3, we need to understand two macros:    1. The cPWR_DeepSleepDurationMs macro in \framework\LowPower\Interface\MKW41Z\PWR_Configuration.h. #ifndef cPWR_DeepSleepDurationMs   #define cPWR_DeepSleepDurationMs                3000 #endif ‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ This macro determines how long the MCU will go to low power mode (deep sleep). The maximum value is 65535000 ms (18.2 h). 2. The THR_SED_POLLING_INTERVAL_MS macro in \source\config.h. /*! The default value for sleepy end device (SED) polling interval */ #ifndef THR_SED_POLLING_INTERVAL_MS     #define THR_SED_POLLING_INTERVAL_MS                     3000     /* Milliseconds */ #endif ‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ This macro determines how often the Low Power End Device will send a poll message to its parent. NOTE: This value does not determine how often the MCU wakes up. The polling interval should be a multiple of the Deep sleep duration value, otherwise the poll will be sent at the next deep sleep time out. As an example, let's say we configure the polling interval to 4000ms and the deep sleep duration to 3000ms. The MCU will wake up every 3000ms but the poll message will be sent every 2 deep sleep timeouts = 6000ms because the timers are synchronized when the MCU wakes up. The following figure shows the behavior of this example. It is recommended that the polling interval is the same as the deep sleep duration, so the MCU doesn't wake up unnecessarily. The following figure shows this behavior. Another macro to keep in mind is THR_SED_TIMEOUT_PERIOD_SEC in app_thread_config.h. #ifndef THR_SED_TIMEOUT_PERIOD_SEC     #define THR_SED_TIMEOUT_PERIOD_SEC                 ((4*THR_SED_POLLING_INTERVAL_MS)/1000 + 3) #endif ‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ This value is the timeout period used by the parent to consider a sleepy end device (SED) disconnected. By default, this value is configured to be 4 times the polling interval + 3s. It is recommended to leave this macro as it is. This value is sent to the parent node during the commissioning.
View full article
Bluetooth® Low Energy (or BLE) is a wireless technology that allows the exchange of information between a device that contains data (Server) and a device that requests that data (Client). Servers are usually small battery powered devices connected to sensors or actuators to gather data or perform some actions while clients are usually devices that use that information in a system or for display to a user (most common client devices are the Smartphones). When creating a custom BLE profile, we need to consider that it will need to be implemented on both Server and Client. Server will include the database of all the information that can be accessed or modified while the Client will require drivers to access and handle the data provided by the server. This post explains how to implement a custom profile in the server side using the NXP BLE stack. As example, a custom Potentiometer reporter is implemented on a MKW40Z160. Generic Attribute Profile Before implementing a custom profile, we need to be familiarized with the way BLE exchanges information. The Generic Attribute Profile (GATT) establishes how to exchange all profile and user data over a BLE connection. All standard BLE profiles are based on GATT and must comply with it to operate correctly. GATT defines two communication roles: Server and Client. The GATT Server stores the data to be transported and accepts GATT requests, commands and confirmations from the client . The GATT Client accesses data on the remote GATT server via read, write, notify or indicate operations. Figure 1 GATT Client-Server GATT data is exposed using attributes that are organized to describe the information accessible in a GATT server. These are Profile, Service, Characteristic and Descriptor. Profiles are high level definitions that determine the behavior of the application as a whole (i.e. Heart Rate Monitor, or Temperature Sensor). Profiles are integrated by one or more Services that define individual functionalities (i.e. a Heart Rate Monitor requires a Heart Rate Sensor and a Battery Measurement Unit). Services are integrated by one or more characteristics that hold individual measurements, control points or other data for a service (i.e. Heart Rate Sensor might have a characteristic for Heart Rate and other for Sensor Location). Finally Descriptors define how characteristics must be accessed. Figure 2 GATT database structure Adding a New Service to the GATT Database The GATT database in a server only includes attributes that describe services, characteristics and descriptors. Profiles are implied since they are a set of predefined services. In the NXP Connectivity Software, macros are used to define each of the attributes present in the database in an easier way. Each service and characteristic in a GATT database has a Universally Unique Identifier (UUID). These UUID are assigned by Bluetooth Org on adopted services and characteristics. When working with custom profiles, a proprietary UUID must be assigned. In the NXP connectivity Software, custom UUIDs are defined in the file gatt_uuid128.h. Each new UUID must be defined using the macro UUID128 (name, bytes) where name is an identifier that will help us to reference the UUID later in the code. Byte is a sequence of 16-bytes (128-bits) which are the custom UUID. Following is an example of the definition of the Potentiometer service and the Potentiometer Relative Value characteristic associated to it. /* Potentiometer Service */ UUID128 ( uuid_service_potentiometer , 0xE0 , 0x1C , 0x4B , 0x5E , 0x1E , 0xEB , 0xA1 , 0x5C , 0xEE , 0xF4 , 0x5E , 0xBA , 0x04 , 0x56 , 0xFF , 0x02 ) /* Potentiometer Characteristic */ UUID128 ( uuid_characteristic_potentiometer_relative_value , 0xE0 , 0x1C , 0x4B , 0x5E , 0x1E , 0xEB , 0xA1 , 0x5C , 0xEE , 0xF4 , 0x5E , 0xBA , 0x04 , 0x57 , 0xFF , 0x02 ) ‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ Once proper UUIDs have been stablished, the new service must be added to the GATT database. It is defined in the file gatt_db.h. Simple macros are used to include each of the attributes in the proper order. Following code shows the implementation of the potentiometer service in gatt_db file. PRIMARY_SERVICE_UUID128(service_potentiometer, uuid_service_potentiometer)     CHARACTERISTIC_UUID128(char_potentiometer_relative_value, uuid_characteristic_potentiometer_relative_value, (gGattCharPropRead_c | gGattCharPropNotify_c))         VALUE_UUID128(value_potentiometer_relative_value, uuid_characteristic_potentiometer_relative_value, (gPermissionFlagReadable_c ), 1, 0x00)         CCCD(cccd_potentiometer)         DESCRIPTOR(cpfd_potentiometer, gBleSig_CharPresFormatDescriptor_d, (gPermissionFlagReadable_c), 7, gCpfdUnsigned8BitInteger, 0x00,                    0xAD/*Unit precentage UUID in Little Endian (Lower byte)*/,                    0x27/*Unit precentage UUID in Little Endian (Higher byte)*/,                    0x01, 0x00, 0x00) ‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ PRIMARY_SERVICE_UUID128 (service_name, service_uuid) defines a new service in the GATT database with a custom 128-bit UUID. It requires two parameters; service_name is the name of this service in the code and it is used later during the program implementation. Service_uuid is the identifier for the service UUID previously defined in gatt_uuid128.h. CHARACTERISTIC_UUID128 (characteristic_name, characteristic_uuid, flags) defines a new characteristic inside the previously defined service with a custom 128-bit UUID. It requires three parameters; characteristic_name is the name of the characteristic in the code, characteristic_uuid is the identifier for the characteristic UUID previously defined in gatt_uuid128.h. Finally, flags is a concatenation of all the characteristic properties (read, write, notify, etc.). VALUE_UUID128 (value_name, characteristic_uuid, permission_flags, number_of_bytes, initial_values…) defines the value in the database of the previously defined characteristic. Value_name is an identifier used later in the code to read or modify the characteristic value. Characteristic_uuid is the same UUID identifier for the previously defined characteristic. Permission_flags determine how the value can be accessed (read, write or both). Number of bytes define the size of the value followed by the initial value of each of those bytes. CCCD (cccd_name) defines a new Client Characteristic Configuration Descriptor for the previously defined characteristic. Cccd_name is the name of the CCCD for use later in the code. This value is optional depending on the characteristic flags. DESCRIPTOR (descriptor_name, descriptor_format, permissions, size, descriptor_bytes…) defines a descriptor for the previously defined characteristic. Descriptor_name defines the name for this descriptor. Descriptor_format determines the type of descriptor. Permissions stablishes how the descriptor is accessed. Finally the size and descriptor bytes are added. All the macros used to fill the GATT database are properly described in the BLEADG (included in the NXP Connectivity Software documentation) under chapter 7 “Creating a GATT Database”. Implementing Drivers for New Service Once the new service has been defined in gatt_db.h, drivers are required to handle the service and properly respond to client requests. To do this, two new files need to be created per every service added to the application; (service name)_service.c and (service name)_interface.h. The service.c file will include all the functions required to handle the service data, and the interface.h file will include all the definitions used by the application to refer to the recently created service. It is recommended to take an existing file for reference. Interface header file shall include the following. Service configuration structure that includes a 16-bit variable for Service Handle and a variable per each characteristic value in the service . /*! Potentiometer Service - Configuration */ typedef struct psConfig_tag {     uint16_t    serviceHandle ;                  /*!<Service handle */     uint8_t     potentiometerValue ;             /*!<Input report field */ } psConfig_t ; ‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ Function declarations for the start service and stop service functions. These are required to initialize/deinitialize a service . bleResult_t Ps_Start ( psConfig_t * pServiceConfig ) ; bleResult_t Ps_Stop ( psConfig_t * pServiceConfig ) ; ‍‍‍ ‍ ‍ ‍ Function declarations for subscribe and unsubscribe functions required to subscribe/unsubscribe a specific client to a service . bleResult_t Ps_Subscribe ( deviceId_t clientDeviceId ) ; bleResult_t Ps_Unsubscribe ( ) ; ‍‍‍ ‍ ‍ ‍ Depending on your application, functions to read, write, update a specific characteristic or a set of them . bleResult_t Ps_RecordPotentiometerMeasurement ( uint16_t serviceHandle , uint8_t newPotentiometerValue ) ; ‍ ‍ Service source file shall include the following. A deviceId_t variable to store the ID for the subscribed client . /*! Potentiometer Service - Subscribed Client*/ static deviceId_t mPs_SubscribedClientId ; ‍‍‍ ‍ ‍ ‍ Function definitions for the Start, Stop, Subscribe and Unsubscribe functions. The Start function may include code to set an initial value to the service characteristic values . bleResult_t Ps_Start ( psConfig_t * pServiceConfig ) {         /* Clear subscibed clien ID (if any) */     mPs_SubscribedClientId = gInvalidDeviceId_c ;         /* Set the initial value defined in pServiceConfig to the characteristic values */     return Ps_RecordPotentiometerMeasurement ( pServiceConfig -> serviceHandle ,                                              pServiceConfig -> potentiometerValue ) ; } bleResult_t Ps_Stop ( psConfig_t * pServiceConfig ) {   /* Unsubscribe current client */     return Ps_Unsubscribe ( ) ; } bleResult_t Ps_Subscribe ( deviceId_t deviceId ) {    /* Subscribe a new client to this service */     mPs_SubscribedClientId = deviceId ;     return gBleSuccess_c ; } bleResult_t Ps_Unsubscribe ( ) {    /* Clear current subscribed client ID */     mPs_SubscribedClientId = gInvalidDeviceId_c ;     return gBleSuccess_c ; } ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ Definition of the service specific functions. It is, the functions used to write, read or notify characteristic values. Our example only implements two; a public function to update a characteristic value in the GATT database, and a local function to issue a notification with the recently updated value to the client . bleResult_t Ps_RecordPotentiometerMeasurement ( uint16_t serviceHandle , uint8_t newPotentiometerValue ) {     uint16_t  handle ;     bleResult_t result ;     /* Get handle of Potentiometer characteristic */     result = GattDb_FindCharValueHandleInService ( serviceHandle ,         gBleUuidType128_c , ( bleUuid_t * ) & potentiometerCharacteristicUuid128 , & handle ) ;     if ( result != gBleSuccess_c )         return result ;     /* Update characteristic value */     result = GattDb_WriteAttribute ( handle , sizeof ( uint8_t ) , ( uint8_t * ) & newPotentiometerValue ) ;     if ( result != gBleSuccess_c )         return result ;     Ps_SendPotentiometerMeasurementNotification ( handle ) ;     return gBleSuccess_c ; } ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ Previous function first obtains the handle value of the characteristic value we want to modify. Handle values are like an index used by the application to access attributes in the database. The UUID for the Potentiometer Relative Value is used to obtain the proper handle by calling GattDb_FindCharValueHandleInService function. Once handle has been obtained, is used in the GattDb_WriteAttribute function to write the new value into the GATT database and it can be accessed by the client. Finally our second function is called to issue a notification . static void Ps_SendPotentiometerMeasurementNotification (   uint16_t handle ) {     uint16_t  hCccd ;     bool_t isNotificationActive ;     /* Get handle of CCCD */     if ( GattDb_FindCccdHandleForCharValueHandle ( handle , & hCccd ) != gBleSuccess_c )         return ;     if ( gBleSuccess_c == Gap_CheckNotificationStatus         ( mPs_SubscribedClientId , hCccd , & isNotificationActive ) &&         TRUE == isNotificationActive )     {         GattServer_SendNotification ( mPs_SubscribedClientId , handle ) ;     } } ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ SendPotentiometerMeasurementNotification sends a notification to the client. It first obtain the handle value of the CCCD we defined in the GATT database for this characteristic. Then, it checks that the CCCD has been written by the client for notifications. If it has, then it sends the notification so the client can perform a read to the characteristic value. All the functions used to access the GATT database and use the GATT server are better explained in the BLEADG document under chapters 6 and 7. Also instructions on how to create a custom profile are included in chapter 8. BLEADG is part of the NXP Connectivity Software documentation. Integrating a New Service to an Existing BLE Project So far a new service has been created in the database and functions to handle it have been defined. Now this new project must be integrated so it can be managed by the NXP Connectivity Stack. Folder structure of an NXP Connectivity Software project is divided in five different modules. App includes all the application files. Bluetooth contains files related with BLE communications. Framework contains auxiliary software used by the stack for the handling of memory, low power etcetera. KSDK contains the Kinetis SDK drivers for low level modules (ADC, GPIO…) and RTOS include files associated with the operating system. Figure 3 Folder structure Service files must be added to the project under the Bluetooth folder, inside the profiles sub-folder. A new folder must be created for the service.c file and the interface.h file must be added under the interface sub-folder. Figure 4 Service files included Once the files are included in the project, the service must be initialized in the stack. File app.c is the main application file for the NXP BLE stack. It calls all the BLE initializations and application callbacks. The service_interface.h file must be included in this file. Figure 5 Interface header inclusion Then in the local variables definition, a new service configuration variable must be defined for the new service. The type of this variable is the one defined in the service interface file and must be initialized with the service name (defined in gattdb.h) and the initial values for all the characteristic values. Figure 6 Service configuration struct The service now must be initialized. It is performed inside the BleApp_Config function by calling the Start function for the recently added service. static void BleApp_Config ( ) {       /* Read public address from controller */     Gap_ReadPublicDeviceAddress ( ) ;     /* Register for callbacks*/     App_RegisterGattServerCallback ( BleApp_GattServerCallback ) ;       .    .    .    mAdvState . advOn = FALSE ;     /* Start services */     Lcs_Start ( & lcsServiceConfig ) ;     Dis_Start ( & disServiceConfig ) ;     Irs_Start ( & irsServiceConfig ) ;     Bcs_Start ( & bcsServiceConfig ) ;     Ps_Start ( & psServiceConfig ) ; ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ Finally, subscribe and unsubscribe functions must be added to the proper host callback. In the BleApp_ConnectionCallback function the subscribe function must be called after the gConnEvtConnected_c (device connected) case, and the unsubscribe function must be called after the gConnEvtDisconnected_c (device disconnected) case. static void BleApp_ConnectionCallback ( deviceId_t peerDeviceId , gapConnectionEvent_t * pConnectionEvent ) {     switch ( pConnectionEvent -> eventType )     {         case gConnEvtConnected_c :         {         .         .         .             /* Subscribe client*/             mPeerDeviceId = peerDeviceId ;             Lcs_Subscribe ( peerDeviceId ) ;             Irs_Subscribe ( peerDeviceId ) ;             Bcs_Subscribe ( peerDeviceId ) ;             Cts_Subscribe ( peerDeviceId ) ;             Ps_Subscribe ( peerDeviceId ) ;             Acs_Subscribe ( peerDeviceId ) ;             Cps_Subscribe ( peerDeviceId ) ;             Rcs_Subscribe ( peerDeviceId ) ;         .         .         .         case gConnEvtDisconnected_c :         {         /* UI */           Led1Off ( ) ;                     /* Unsubscribe client */           mPeerDeviceId = gInvalidDeviceId_c ;           Lcs_Unsubscribe ( ) ;           Irs_Unsubscribe ( ) ;           Bcs_Unsubscribe ( ) ;           Cts_Unsubscribe ( ) ;           Ps_Unsubscribe ( ) ;           Acs_Unsubscribe ( ) ;           Cps_Unsubscribe ( ) ;           Rcs_Unsubscribe ( ) ; ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ After this, services can be accessed by a client application. Handling Notifications and Write Requests Once the new service has been initialized, it is possible for the client to access GATT database attributes and issue commands (read, write, notify…). Nevertheless, when an attribute is written or a CCCD is set to start notifications, program must be aware of these requests to handle them if required. Handling Notifications When a characteristic has been configured as notifiable, the client expects to receive messages from it every time in a while depending on the pre-configured parameters. To indicate this, the client writes the specific CCCD for the characteristic indicating that notifications must start/stop being sent. When this occurs, BleApp_GattServerCallback is executed in the main program. All the application CCCDs must be monitored when the gEvtCharacteristicCccdWritten_c event is set. This event indicates that a CCCD has been written. A conditional structure must be programmed to determine which CCCD was modified and act accordingly. static void BleApp_GattServerCallback ( deviceId_t deviceId , gattServerEvent_t * pServerEvent ) {     switch ( pServerEvent -> eventType )     {       case gEvtCharacteristicCccdWritten_c :         {             /*             Attribute CCCD write handler: Create a case for your registered attribute and             execute callback action accordingly             */             switch ( pServerEvent -> eventData . charCccdWrittenEvent . handle )             {             case cccd_input_report : {               //Determine if the timer must be started or stopped               if ( pServerEvent -> eventData . charCccdWrittenEvent . newCccd ) {                 // CCCD set, start timer                 TMR_StartTimer ( tsiTimerId , gTmrIntervalTimer_c , gTsiUpdateTime_c , BleApp_TsiSensorTimer , NULL ) ; #if gAllowUartDebug                 Serial_Print ( debugUartId , "Input Report notifications enabled \n\r" , gNoBlock_d ) ; #endif               }               else {                 // CCCD cleared, stop timer                 TMR_StopTimer ( tsiTimerId ) ; #if gAllowUartDebug                 Serial_Print ( debugUartId , "Input Report notifications disabled \n\r" , gNoBlock_d ) ; #endif               }             }               break ;                           case cccd_potentiometer : {               //Determine if the timer must be started or stopped               if ( pServerEvent -> eventData . charCccdWrittenEvent . newCccd ) {                 // CCCD set, start timer                 TMR_StartTimer ( potTimerId , gTmrIntervalTimer_c , gPotentiometerUpdateTime_c , BleApp_PotentiometerTimer , NULL ) ; #if gAllowUartDebug                 Serial_Print ( debugUartId , "Potentiometer notifications enabled \n\r" , gNoBlock_d ) ; #endif               }               else {                 // CCCD cleared, stop timer                 TMR_StopTimer ( potTimerId ) ; #if gAllowUartDebug                 Serial_Print ( debugUartId , "Potentiometer notifications disabled \n\r" , gNoBlock_d ) ; #endif               }             }               break ; ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ In this example, when the gEvtCharacteristicCccdWritten_c is set a switch-case selector is executed to determine the written CCCD. This is done by reading the pServerEvent structure in the eventData.charCccdWrittenEvent.handle field. The obtained handle must be compared with the name of the CCCD defined in gatt_db.h for each notifiable characteristic. Figure 7 CCCD name Once the correct CCCD has been detected, the program must determine if it was set or clear. This is done by reading the pServerEvent structure in the eventData.charCccdWrittenEvent.newCccd and executing an action accordingly. In the example code, a timer is started or stopped. Once this timer reaches its modulo value, a new notification is sent using the Ps_RecordPotentiometerMeasurement function previously defined in the service files (see Implementing Drivers for New Service). Handling Write Requests Write request callbacks are not automatically generated like the notification ones. They must be registered during the application initialization. Something to take into account is when this feature is enabled, the written value is not automatically stored in the GATT database. Developers must implement code to do this and perform other application actions if needed.To do this, the GattServer_RegisterHandlesForWriteNotifications function must be called including the handles of all the characteristics that are wanted to generate a callback when written. * Configure writtable attributes that require a callback action * /     uint16_t notifiableHandleArray [ ] = { value_led_control , value_buzzer , value_accelerometer_scale , value_controller_command , value_controller_configuration } ;     uint8_t notifiableHandleCount = sizeof ( notifiableHandleArray ) / 2 ;     bleResult_t initializationResult = GattServer_RegisterHandlesForWriteNotifications ( notifiableHandleCount , ( uint16_t * ) & notifiableHandleArray [ 0 ] ) ; ‍‍‍‍ ‍ ‍ ‍ ‍ ‍ In this example, an array with all the writable characteristics was created. The function that register callbacks requires the quantity of characteristic handles to be registered and the pointer to an array with all the handles. After a client has connected, the gEvtAttributeWritten_c will be executed inside the function BleApp_GattServerCallback every time one of the configured characteristics has been written. Variable pServerEvent->eventData.attributeWrittenEvent.handle must be read to determine the handle of the written characteristic and perform an action accordingly. Depending on the user application, the GATT database must be updated with the new value. To do this, function GattDb_WriteAttribute must be executed. It is recommended to create a function inside the service.c file that updates the attribute in database. case gEvtAttributeWritten_c:         {             /*             Attribute write handler: Create a case for your registered attribute and             execute callback action accordingly             */             switch(pServerEvent->eventData.attributeWrittenEvent.handle){               case value_led_control:{                 bleResult_t result;                                 //Get written value                 uint8_t* pAttWrittenValue = pServerEvent->eventData.attributeWrittenEvent.aValue;                                 //Create a new instance of the LED configurator structure                 lcsConfig_t lcs_LedConfigurator = {                   .serviceHandle = service_led_control,                   .ledControl.ledNumber = (uint8_t)*pAttWrittenValue,                   .ledControl.ledCommand = (uint8_t)*(pAttWrittenValue + sizeof(uint8_t)),                 };                                 //Call LED update function                 result = Lcs_SetNewLedValue(&lcs_LedConfigurator);                                 //Send response to client                 BleApp_SendAttWriteResponse(&deviceId, pServerEvent, &result);                               }               break; ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ After all the required actions have been executed, server must send a response to the client. To do this, function GattServer_SendAttributeWrittenStatus is called including the handle and the error code for the client (OK or any other error status). static void BleApp_SendAttWriteResponse ( deviceId_t * pDeviceId , gattServerEvent_t * pGattServerEvent , bleResult_t * pResult ) {   attErrorCode_t attErrorCode ;     // Determine response to send (OK or Error)   if ( * pResult == gBleSuccess_c )     attErrorCode = gAttErrCodeNoError_c ;   else {     attErrorCode = ( attErrorCode_t ) ( * pResult & 0x00FF ) ;   }   // Send response to client    GattServer_SendAttributeWrittenStatus ( * pDeviceId , pGattServerEvent -> eventData . attributeWrittenEvent . handle , attErrorCode ) ; } ‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ More information on how to handle writable characteristics can be found in the BLEADG Chapter 5 (Included in the NXP Connectivity Software documentation). References Bluetooth® Low Energy Application Developer’s Guide (BLEADG)– Included in the NXP Connectivity Software Documentation FRDM-KW40Z Demo Application - Link
View full article
In developing a Zigbee application, certain static configuration is required before the application is built. C onfiguring the network size, adding a new cluster, making the device discoverable and adding a new endpoint can be done by changing parameters in the following files: app_zps_cfg.h app_zcl_cfg.h app_zcl_global.c These files are responsible for setting up network parameters like device type and associated parameters, mainly related to the APS and NWK layers of the ZigBee PRO stack. Network Configuration The ZigBee device can be configured to be a coordinator, router and end device. The following section details the way in which the user can configure each device type. The app_zps_cfg header file lets the user configure the ZPS ZDO parameters of the node. The following macros are necessary for the corresponding device types: For coordinator in a ZigBee network #define ZPS_COORDINATOR #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_COORD For router in a ZigBee network #define ZPS_ROUTER #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_ROUTER For enddevice in a ZigBee network #define ZPS_ENDDEVICE #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_ENDDEVICE Other ZPS ZDO configurations which are defined using macro are explained in comments inside the header file (app_zps_cfg.h). These macros provide the user with the ability to configure the device according to their network needs. The type of security for the ZigBee network can also be configured by the macro ZPS_ZDO_NWK_KEY_STATE. The user can change the security type to no network security (ZPS_ZDO_NO_NETWORK_KEY), pre-configured link key security (ZPS_ZDO_PRECONFIGURED_LINK_KEY), distributed link key security (ZPS_ZDO_DISTRIBUTED_LINK_KEY) or pre-configured installation code security (ZPS_ZDO_PRCONFIGURED_INSTALLATION_CODE). /* Specify No network Security */ #define ZPS_ZDO_NWK_KEY_STATE                               ZPS_ZDO_NO_NETWORK_KEY The application allows through this header file to configure ZPS APS AIB parameters, like extended PANID (ZPS_APS_AIB_INIT_USE_EXTENDED_PANID) or channel mask (ZPS_APS_AIB_INIT_CHANNEL_MASK). /* NWK EXTENDED PANID (EPID) that the device will use.*/ #define ZPS_APS_AIB_INIT_USE_EXTENDED_PANID                 0x0000000000000000ULL /*! CHANNEL MASK : Define all channels from 11 to 26*/ #define ZPS_APS_AIB_INIT_CHANNEL_MASK                       0x07fff800UL User can also configure the simple descriptor table size (AF_SIMPLE_DESCRIPTOR_TABLE_SIZE) as part of the ZPS AF Layer configuration parameters.The value depends on number of endpoints defined in application, one endpoint is always reserved for ZDO . So, for a device with one endpoint, the value would be 2 (1 ZDO + 1 application endpoint) #define AF_SIMPLE_DESCRIPTOR_TABLE_SIZE                     2 Among other ZPS network configuration parameters that can be changed by the user are scan duration (ZPS_SCAN_DURATION), default permit joining time (ZPS_DEFAULT_PERMIT_JOINING_TIME) and the maximum number of simultaneous key requests (ZPS_MAX_NUM_SIMULTANEOUS_REQUEST_KEY_REQS). Also, NIB values can be changed, like for example, the maximum number of routers in the network (ZPS_NWK_NIB_INIT_MAX_ROUTERS), the maximum number of children for a node (ZPS_NWK_NIB_INIT_MAX_CHILDREN), the maximum network depth (ZPS_NWK_NIB_INIT_MAX_DEPTH) or the network security level (ZPS_NWK_NIB_INIT_SECURITY_LEVEL). Different ZigBee network table sizes can be adjusted by the user from this header file. The important tables are mentioned below: The active neighbor table size (ZPS_NEIGHBOUR_TABLE_SIZE). The neighbor discovery table size, used to keep a list of the neighboring devices associated with the node (ZPS_NEIGHBOUR_DISCOVERY_TABLE_SIZE). The network address map table size, which represents the size of the address map that maps 64-bit IEEE addresses to 16-bit network (short) addresses (ZPS_ADDRESS_MAP_TABLE_SIZE). The network security material set size (ZPS_SECURITY_MATERIAL_SETS). The broadcast transaction table size, which stores the records of the broadcast messages received by the node (ZPS_BROADCAST_TRANSACTION_TABLE_SIZE). The route record table size (ZPS_ROUTE_RECORD_TABLE_SIZE) for the table that records each route, storing the destination network address, a count of the number of relay nodes to reach the destination and a list of the network addresses of the relay nodes. The route discovery table size (ZPS_ROUTE_DISCOVERY_TABLE_SIZE), used by the node to store temporary information used during route discovery. The MAC address table size (ZPS_MAC_ADDRESS_TABLE_SIZE). The binding table size (ZPS_BINDING_TABLE_SIZE). The group table size (ZPS_GROUP_TABLE_SIZE). The number of supported network keys, known also as the security material sets (ZPS_KEY_TABLE_SIZE). The child table size (ZPS_CHILD_TABLE_SIZE), that gives the size of the persisted sub-table of the active neighbor table. The stored entries are for the node’s parent and immediate children. The trust center device table size (ZPS_TRUST_CENTER_DEVICE_TABLE_SIZE). ZCL Configuration The app_zcl_cfg header file is used by the application to configure the ZigBee Cluster library. This file contains the definition for the application profile and cluster ids. The default application profiles are ZDP, HA, ZLO, GP. The ZDP (ZigBee Device Profile) id is identified by the following line: #define ZDP_PROFILE_ID             (0x0000) ZDP provides services for the following categories as cluster Ids: Device discovery services (for example, ZDP_DISCOVERY_CACHE_REQ_CLUSTER_ID) Service discovery services (for example, ZDP_IEEE_ADDR_REQ_CLUSTER_ID) Binding services (for example, ZDP_BIND_RSP_CLUSTER_ID) Management services (for example, ZDP_MGMT_NWK_DISC_REQ_CLUSTER_ID) The HA (Home Automation) profile id is identified by the following line: #define HA_PROFILE_ID             (0x0104) HA provides services for the following categories as cluster Ids: Generic devices (for example, HA_BASIC_CLUSTER_ID) Lighting devices (for example, HA_LEVELCONTROL_CLUSTER_ID) Intruder Alarm System (IAS) devices (for example, HA_IASZONE_CLUSTER_ID) The ZLO (ZigBee Lighting and Occupancy) profile is not an application profile but devices in this collection use the same application profile id as for the Home Automation application profile. This ensures backward compatibility with applications for devices based on the Home Automation 1.2 profile. ZigBee Green Power (GP) is an optional cluster with the aim of minimizing the power demands on a network node in order to support: Nodes that are completely self-powered through energy harvesting Battery-powered nodes that require ultra-long battery life The GP profile id is identified by the following line: #define GP_PROFILE_ID               (0xa1e0) The Zigbee GP cluster ID is defined as following: #define GP_GREENPOWER_CLUSTER_ID    (0x0021) Depending on the application, the app_zcl_cfg header file also contains the defines for the node endpoints. For example, the occupancy_sensor application contains the following endpoints: /* Node 'Coordinator' */ /* Endpoints */ #define COORDINATOR_ZDO_ENDPOINT    (0) #define COORDINATOR_COORD_ENDPOINT    (1) /* Node 'OccupancySensor' */ /* Endpoints */ #define OCCUPANCYSENSOR_ZDO_ENDPOINT    (0) #define OCCUPANCYSENSOR_SENSOR_ENDPOINT    (1)   /* Node 'LightSensor' */ /* Endpoints */ #define LIGHTSENSOR_ZDO_ENDPOINT    (0) #define LIGHTSENSOR_SENSOR_ENDPOINT    (1)   /* Node 'LightTemperatureOccupancySensor' */ /* Endpoints */ #define LIGHTTEMPERATUREOCCUPANCYSENSOR_ZDO_ENDPOINT    (0) #define LIGHTTEMPERATUREOCCUPANCYSENSOR_SENSOR_ENDPOINT    (1) The source file app_zcl_globals.c is used to declare the cluster lists for each endpoint. These act as simple descriptors for the node. Each endpoint has two cluster lists, containing uint16_t data. One is for input and one for output. The sizes of these two lists must be equal. For example, for endpoint 0, the declared lists will be the following: PRIVATE const uint16 s_au16Endpoint0InputClusterList[16]  =  { 0x0000, 0x0001, 0x0002, 0x0003, 0x0004, 0x0005, 0x0006 , 0x0007, \                                                               0x0008, 0x0010, 0x0011, 0x0012, 0x0012, 0x0013, 0x0014 , 0x0015}; PRIVATE const uint16 s_au16Endpoint0OutputClusterList[16] = { 0x0000, 0x0001, 0x0002, 0x0003, 0x0004, 0x0005, 0x0006 , 0x0007, \                                                              0x0008, 0x0010, 0x0011, 0x0012, 0x0012, 0x0013, 0x0014 , 0x0015}; The input list must also have a corresponding cluster APDU list, matching in size. For the endpoint 0 example, this will look like: PRIVATE const PDUM_thAPdu s_ahEndpoint0InputClusterAPdus[16] = { apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP , apduZDP, apduZDP,\                                                                  apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP , apduZDP, apduZDP}; Each output and input cluster list has a corresponding cluster discovery enabled flags list. As each bit inside the Cluster Disc Flag corresponds to cluster , for 16 clusters declared in Input and Output cluster list, one needs 2 bytes for Discoverable flag. In this example, the declaration is the following: PRIVATE uint8 s_au8Endpoint0InputClusterDiscFlags[2] = {0x1F, 0x08}; PRIVATE uint8 s_au8Endpoint0OutputClusterDiscFlags[2] = {0x08, 0x1B}; These parameters are registered in the node’s endpoints simple descriptor structure. The declared variable for the structure is s_asSimpleDescConts and its size depends on the number of endpoints available on the node. For example, for two endpoints, the declaration will be as below: PUBLIC zps_tsAplAfSimpleDescCont s_asSimpleDescConts[2] = {     {         {             0x0000,             0,             0,             0,             84,             84,             s_au16Endpoint0InputClusterList,             s_au16Endpoint0OutputClusterList,             s_au8Endpoint0InputClusterDiscFlags,             s_au8Endpoint0OutputClusterDiscFlags,         },         s_ahEndpoint0InputClusterAPdus,         1     },     {         {             0x0104,             0,             0,             1,             6,             4,             s_au16Endpoint1InputClusterList,             s_au16Endpoint1OutputClusterList,             s_au8Endpoint1InputClusterDiscFlags,             s_au8Endpoint1OutputClusterDiscFlags,         },         s_ahEndpoint1InputClusterAPdus,         1     }, }; The AF Context definition is as below: typedef struct _zps_tsAplAfSimpleDescCont {     ZPS_tsAplAfSimpleDescriptor sSimpleDesc;     const PDUM_thAPdu *phAPduInClusters;     bool_t bEnabled; } zps_tsAplAfSimpleDescCont; And the endpoint simple descriptor has the following structure definition: typedef struct {     uint16 u16ApplicationProfileId;     uint16 u16DeviceId;     uint8  u8DeviceVersion;     uint8  u8Endpoint;     uint8  u8InClusterCount;     uint8  u8OutClusterCount;     const uint16 *pu16InClusterList;     const uint16 *pu16OutClusterList;     uint8 *au8InDiscoveryEnabledFlags;     uint8 *au8OutDiscoveryEnabledFlags; } ZPS_tsAplAfSimpleDescriptor;
View full article
This document describes how to add additional endpoints to the Router application in the AN12061-MKW41Z-AN-Zigbee-3-0-Base-Device Application Note.   The Router application's main endpoint acts as a light controlled by the On/Off cluster acting as a Server. The steps below describe how to add two new endpoints with On/Off clusters acting as clients.   Note that these changes only go as far as making the new endpoints discoverable, no functionality has been added to read inputs and transmit commands from the new endpoints. Router/app_zcl_cfg.h The first step is to add the new endpoints (Switch1, Switch2) into ZCL configuration file. /* Endpoints */ #define ROUTER_ZDO_ENDPOINT         (0) #define ROUTER_APPLICATION_ENDPOINT (1) #define ROUTER_SWITCH1_ENDPOINT     (2) #define ROUTER_SWITCH2_ENDPOINT     (3) Router/app_zps_cfg.h The second step is to update the ZigBee Configuration file to increase the simple descriptor table size from 2 to 4, as it is the number of application endpoints (3 in our case) + 1 (ZDO endpoint).  : /*****************************************************************************/ /* ZPS AF Layer Configuration Parameters */ /*****************************************************************************/ #define AF_SIMPLE_DESCRIPTOR_TABLE_SIZE 4 Router/app_zcl_globals.c The third step is to update the ZigBee cluster Configuration file to add the new endpoints (Switch1, Switch2) and their clusters to the Router application. For that one need to change the Configured endpoint from 1 to 3 and also the Endpoint Map list present as below: PUBLIC uint8 u8MaxZpsConfigEp = 3; PUBLIC uint8 au8EpMapPresent[3] = { ROUTER_APPLICATION_ENDPOINT , ROUTER_SWITCH1_ENDPOINT , ROUTER_SWITCH2_ENDPOINT }; The Switch 1 and Switch 2 contains Basic Cluster (0x0000) Server and Client, Identify Cluster (0x0003) Server and Client, OnOff Cluster (0x0006) Client, Group Cluster (0x004) Client. The clusters are added to the Input cluster list (Server side) and output cluster list (Client side) but made discoverable using DiscFlag only for the cluster list which is enabled. So, assuming you need to add OnOff cluster client, you would need to use add the cluster id (0x0006 for OnOff) into input cluster list (Server side of cluster) and output cluster list (Client side of the cluster) and make it discoverable for output cluster list as it is a client cluster. PRIVATE const uint16 s_au16Endpoint2InputClusterList[5] = { HA_BASIC_CLUSTER_ID , HA_GROUPS_CLUSTER_ID , HA_IDENTIFY_CLUSTER_ID ,\ HA_ONOFF_CLUSTER_ID , HA_DEFAULT_CLUSTER_ID , }; PRIVATE const PDUM_thAPdu s_ahEndpoint2InputClusterAPdus[5] = { apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, }; PRIVATE uint8 s_au8Endpoint2InputClusterDiscFlags[1] = { 0x05 }; PRIVATE const uint16 s_au16Endpoint2OutputClusterList[4] = { HA_BASIC_CLUSTER_ID , HA_GROUPS_CLUSTER_ID , HA_IDENTIFY_CLUSTER_ID ,\ HA_ONOFF_CLUSTER_ID , }; PRIVATE uint8 s_au8Endpoint2OutputClusterDiscFlags[1] = { 0x0f }; PRIVATE const uint16 s_au16Endpoint3InputClusterList[5] = { HA_BASIC_CLUSTER_ID , HA_GROUPS_CLUSTER_ID , HA_IDENTIFY_CLUSTER_ID ,\ HA_ONOFF_CLUSTER_ID , HA_DEFAULT_CLUSTER_ID , }; PRIVATE const PDUM_thAPdu s_ahEndpoint3InputClusterAPdus[5] = { apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, }; PRIVATE uint8 s_au8Endpoint3InputClusterDiscFlags[1] = { 0x05 }; PRIVATE const uint16 s_au16Endpoint3OutputClusterList[4] = { HA_BASIC_CLUSTER_ID , HA_GROUPS_CLUSTER_ID , HA_IDENTIFY_CLUSTER_ID ,\ HA_ONOFF_CLUSTER_ID , }; PRIVATE uint8 s_au8Endpoint3OutputClusterDiscFlags[1] = { 0x0f }; Now add these newly added endpoints as part of Simple Descriptor structure and initialize the structure (see the declaration of zps_tsAplAfSimpleDescCont and ZPS_tsAplAfSimpleDescriptor structures to understand how to correctly fill the various parameters) correctly as below : PUBLIC zps_tsAplAfSimpleDescCont s_asSimpleDescConts[AF_SIMPLE_DESCRIPTOR_TABLE_SIZE] = { {    {       0x0000,       0,       0,       0,       84,       84,       s_au16Endpoint0InputClusterList,       s_au16Endpoint0OutputClusterList,       s_au8Endpoint0InputClusterDiscFlags,       s_au8Endpoint0OutputClusterDiscFlags,    },    s_ahEndpoint0InputClusterAPdus,    1 }, {    {       0x0104,       0,       1,       1,       5,       4,       s_au16Endpoint1InputClusterList,       s_au16Endpoint1OutputClusterList,       s_au8Endpoint1InputClusterDiscFlags,       s_au8Endpoint1OutputClusterDiscFlags,    },    s_ahEndpoint1InputClusterAPdus,    1 }, {    {       0x0104,       0,       1,       2,       5,       4,       s_au16Endpoint2InputClusterList,       s_au16Endpoint2OutputClusterList,       s_au8Endpoint2InputClusterDiscFlags,       s_au8Endpoint2OutputClusterDiscFlags,     },     s_ahEndpoint2InputClusterAPdus,    1 }, {    {       0x0104,       0,       1,       3,       5,       4,       s_au16Endpoint3InputClusterList,       s_au16Endpoint3OutputClusterList,       s_au8Endpoint3InputClusterDiscFlags,       s_au8Endpoint3OutputClusterDiscFlags,    },    s_ahEndpoint3InputClusterAPdus,    1 }, }; Router/zcl_options.h This file is used to set the options used by the ZCL.   Number of Endpoints The number of endpoints is increased from 1 to 3: /* Number of endpoints supported by this device */ #define ZCL_NUMBER_OF_ENDPOINTS                              3   Enable Client Clusters The client cluster functionality for the new endpoints is enabled: /****************************************************************************/ /*                             Enable Cluster                               */ /*                                                                          */ /* Add the following #define's to your zcl_options.h file to enable         */ /* cluster and their client or server instances                             */ /****************************************************************************/ #define CLD_BASIC #define BASIC_SERVER #define BASIC_CLIENT #define CLD_IDENTIFY #define IDENTIFY_SERVER #define IDENTIFY_CLIENT #define CLD_GROUPS #define GROUPS_SERVER #define GROUPS_CLIENT #define CLD_ONOFF #define ONOFF_SERVER #define ONOFF_CLIENT   Router/app_zcl_task.c Base Device Data Structures The structures that store data for the new Base Devices associated with the new endpoints are created: /****************************************************************************/ /***        Exported Variables                                            ***/ /****************************************************************************/ tsZHA_BaseDevice sBaseDevice ; tsZHA_BaseDevice sBaseDeviceSwitch1 ; tsZHA_BaseDevice sBaseDeviceSwitch2 ;   Register Base Device Endpoints - APP_ZCL_vInitialise() The two new Base Devices and their endpoints are registered with the stack to make them available: if ( eZCL_Status != E_ZCL_SUCCESS ) {           DBG_vPrintf ( TRACE_ZCL , "Error: eZHA_RegisterBaseDeviceEndPoint(Light): %02x\r\n" , eZCL_Status ) ; } /* Register Switch1 EndPoint */ eZCL_Status =   eZHA_RegisterBaseDeviceEndPoint ( ROUTER_SWITCH1_ENDPOINT ,                                                           & APP_ZCL_cbEndpointCallback ,                                                           & sBaseDeviceSwitch1 ) ; if ( eZCL_Status != E_ZCL_SUCCESS ) {           DBG_vPrintf ( TRACE_ZCL , "Error: eZHA_RegisterBaseDeviceEndPoint(Switch1): %02x\r\n" , eZCL_Status ) ; } /* Register Switch2 EndPoint */ eZCL_Status =   eZHA_RegisterBaseDeviceEndPoint ( ROUTER_SWITCH2_ENDPOINT ,                                                           & APP_ZCL_cbEndpointCallback ,                                                           & sBaseDeviceSwitch2 ) ; if ( eZCL_Status != E_ZCL_SUCCESS ) {           DBG_vPrintf ( TRACE_ZCL , "Error: eZHA_RegisterBaseDeviceEndPoint(Switch2): %02x\r\n" , eZCL_Status ) ; }   Factory Reset Functionality - vHandleClusterCustomCommands() The two new Base Devices are factory reset by re-registering them when the Reset To Factory Defaults command is received by the Basic cluster server: case GENERAL_CLUSTER_ID_BASIC : {      tsCLD_BasicCallBackMessage * psCallBackMessage = ( tsCLD_BasicCallBackMessage * ) psEvent -> uMessage . sClusterCustomMessage . pvCustomData ;      if ( psCallBackMessage -> u8CommandId == E_CLD_BASIC_CMD_RESET_TO_FACTORY_DEFAULTS )      {           DBG_vPrintf ( TRACE_ZCL , "Basic Factory Reset Received\n" ) ;           FLib_MemSet ( & sBaseDevice , 0 , sizeof ( tsZHA_BaseDevice ) ) ;           APP_vZCL_DeviceSpecific_Init ( ) ;           eZHA_RegisterBaseDeviceEndPoint ( ROUTER_APPLICATION_ENDPOINT ,                                                   & APP_ZCL_cbEndpointCallback ,                                                   & sBaseDevice ) ;           eZHA_RegisterBaseDeviceEndPoint ( ROUTER_SWITCH1_ENDPOINT ,                                                   & APP_ZCL_cbEndpointCallback ,                                                   & sBaseDeviceSwitch1 ) ;           eZHA_RegisterBaseDeviceEndPoint ( ROUTER_SWITCH2_ENDPOINT ,                                                   & APP_ZCL_cbEndpointCallback ,                                                   & sBaseDeviceSwitch2 ) ;      } } break ;   Basic Server Cluster Data Initialisation - APP_vZCL_DeviceSpecific_Init() The default attribute values for the Basic clusters are initialized: sBaseDevice . sOnOffServerCluster . bOnOff = FALSE ; FLib_MemCpy ( sBaseDevice . sBasicServerCluster . au8ManufacturerName , "NXP" , CLD_BAS_MANUF_NAME_SIZE ) ; FLib_MemCpy ( sBaseDevice . sBasicServerCluster . au8ModelIdentifier , "BDB-Router" , CLD_BAS_MODEL_ID_SIZE ) ; FLib_MemCpy ( sBaseDevice . sBasicServerCluster . au8DateCode , "20150212" , CLD_BAS_DATE_SIZE ) ; FLib_MemCpy ( sBaseDevice . sBasicServerCluster . au8SWBuildID , "1000-0001" , CLD_BAS_SW_BUILD_SIZE ) ; sBaseDeviceSwitch1 . sOnOffServerCluster . bOnOff = FALSE ; FLib_MemCpy ( sBaseDeviceSwitch1 . sBasicServerCluster . au8ManufacturerName , "NXP" , CLD_BAS_MANUF_NAME_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch1 . sBasicServerCluster . au8ModelIdentifier , "BDB-Sw1" , CLD_BAS_MODEL_ID_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch1 . sBasicServerCluster . au8DateCode , "20170310" , CLD_BAS_DATE_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch1 . sBasicServerCluster . au8SWBuildID , "1000-0001" , CLD_BAS_SW_BUILD_SIZE ) ; sBaseDeviceSwitch2 . sOnOffServerCluster . bOnOff = FALSE ; FLib_MemCpy ( sBaseDeviceSwitch2 . sBasicServerCluster . au8ManufacturerName , "NXP" , CLD_BAS_MANUF_NAME_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch2 . sBasicServerCluster . au8ModelIdentifier , "BDB-Sw2" , CLD_BAS_MODEL_ID_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch2 . sBasicServerCluster . au8DateCode , "20170310" , CLD_BAS_DATE_SIZE ) ; FLib_MemCpy ( sBaseDeviceSwitch2 . sBasicServerCluster . au8SWBuildID , "1000-0001" , CLD_BAS_SW_BUILD_SIZE ) ;   Router/app_zcl_task.h The Base Device Data structures are made available to other modules: /****************************************************************************/ /***        Exported Variables                                            ***/ /****************************************************************************/ extern tsZHA_BaseDevice sBaseDevice ; extern tsZHA_BaseDevice sBaseDeviceSwitch1 ; extern tsZHA_BaseDevice sBaseDeviceSwitch2 ;   Router/app_router_node.c Enable ZCL Event Handler - vAppHandleAfEvent() Data messages addressed to the two new endpoints are passed to the ZCL for processing: if ( psZpsAfEvent -> u8EndPoint == ROUTER_APPLICATION_ENDPOINT ||   psZpsAfEvent -> u8EndPoint == ROUTER_SWITCH1_ENDPOINT ||   psZpsAfEvent -> u8EndPoint == ROUTER_SWITCH2_ENDPOINT ) {      DBG_vPrintf ( TRACE_APP , "Pass to ZCL\n" ) ;      if ( ( psZpsAfEvent -> sStackEvent . eType == ZPS_EVENT_APS_DATA_INDICATION ) ||           ( psZpsAfEvent -> sStackEvent . eType == ZPS_EVENT_APS_INTERPAN_DATA_INDICATION ) )      {           APP_ZCL_vEventHandler ( & psZpsAfEvent -> sStackEvent ) ;       } }
View full article
In this document we will be seeing how to create a BLE demo application for an adopted BLE profile based on another demo application with a different profile. In this demo, the Pulse Oximeter Profile will be implemented.  The PLX (Pulse Oximeter) Profile was adopted by the Bluetooth SIG on 14th of July 2015. You can download the adopted profile and services specifications on https://www.bluetooth.org/en-us/specification/adopted-specifications. The files that will be modified in this post are, app.c,  app_config.c, app_preinclude.h, gatt_db.h, pulse_oximeter_service.c and pulse_oximeter_interface.h. A profile can have many services, the specification for the PLX profile defines which services need to be instantiated. The following table shows the Sensor Service Requirements. Service Sensor Pulse Oximeter Service Mandatory Device Information Service Mandatory Current Time Service Optional Bond Management Service Optional Battery Service Optional Table 1. Sensor Service Requirements For this demo we will instantiate the PLX service, the Device Information Service and the Battery Service. Each service has a source file and an interface file, the device information and battery services are already implemented, so we will only need to create the pulse_oximeter_interface.h file and the pulse_oximeter_service.c file. The PLX Service also has some requirements, these can be seen in the PLX service specification. The characteristic requirements for this service are shown in the table below. Characteristic Name Requirement Mandatory Properties Security Permissions PLX Spot-check Measurement C1 Indicate None PLX Continuous Measurement C1 Notify None PLX Features Mandatory Read None Record Access Control Point C2 Indicate, Write None Table 2. Pulse Oximeter Service Characteristics C1: Mandatory to support at least one of these characteristics. C2: Mandatory if measurement storage is supported for Spot-check measurements. For this demo, all the characteristics will be supported. Create a folder for the pulse oximeter service in  \ConnSw\bluetooth\profiles named pulse_oximeter and create the pulse_oximeter_service.c file. Next, go to the interface folder in \ConnSw\bluetooth\profiles and create the pulse_oximeter_interface.h file. At this point these files will be blank, but as we advance in the document we will be adding the service implementation and the interface macros and declarations. Clonate a BLE project with the cloner tool. For this demo the heart rate sensor project was clonated. You can choose an RTOS between bare metal or FreeRTOS. You will need to change some workspace configuration.  In the bluetooth->profiles->interface group, remove the interface file for the heart rate service and add the interface file that we just created. Rename the group named heart_rate in the bluetooth->profiles group to pulse_oximeter and remove the heart rate service source file and add the pulse_oximeter_service.c source file. These changes will be saved on the actual workspace, so if you change your RTOS you need to reconfigure your workspace. To change the device name that will be advertised you have to change the advertising structure located in app_config.h. /* Scanning and Advertising Data */ static const uint8_t adData0 [ 1 ] = { ( gapAdTypeFlags_t ) ( gLeGeneralDiscoverableMode_c | gBrEdrNotSupported_c ) } ; static const uint8_t adData1 [ 2 ] = { UuidArray ( gBleSig_PulseOximeterService_d ) } ; static const gapAdStructure_t advScanStruct [ ] = { { . length = NumberOfElements ( adData0 ) + 1 , . adType = gAdFlags_c , . aData = ( void * ) adData0 } , { . length = NumberOfElements ( adData1 ) + 1 , . adType = gAdIncomplete16bitServiceList_c , . aData = ( void * ) adData1 } , { . adType = gAdShortenedLocalName_c , . length = 8 , . aData = "FSL_PLX" } } ; ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ We also need to change the address of the device so we do not have conflicts with another device with the same address. The definition for the address is located in app_preinclude.h and is called BD_ADDR. In the demo it was changed to: #define BD_ADDR 0xBE,0x00,0x00,0x9F,0x04,0x00 ‍ ‍ ‍ Add the definitions in ble_sig_defines.h located in Bluetooth->host->interface for the UUID’s of the PLX service and its characteristics. /*! Pulse Oximeter Service UUID */ #define gBleSig_PulseOximeterService_d 0x1822 /*! PLX Spot-Check Measurement Characteristic UUID */ #define gBleSig_PLXSpotCheckMeasurement_d 0x2A5E /*! PLX Continuous Measurement Characteristic UUID */ #define gBleSig_PLXContinuousMeasurement_d 0x2A5F /*! PLX Features Characteristic UUID */ #define gBleSig_PLXFeatures_d 0x2A60 ‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ We need to create the GATT database for the pulse oximeter service. The requirements for the service can be found in the PLX Service specification. The database is created at compile time and is defined in the gatt_db.h.  Each characteristic can have certain properties such as read, write, notify, indicate, etc. We will modify the existing database according to our needs. The database for the pulse oximeter service should look something like this. PRIMARY_SERVICE ( service_pulse_oximeter , gBleSig_PulseOximeterService_d ) CHARACTERISTIC ( char_plx_spotcheck_measurement , gBleSig_PLXSpotCheckMeasurement_d , ( gGattCharPropIndicate_c ) ) VALUE_VARLEN ( value_PLX_spotcheck_measurement , gBleSig_PLXSpotCheckMeasurement_d , ( gPermissionNone_c ) , 19 , 3 , 0x00 , 0x00 , 0x00 ) CCCD ( cccd_PLX_spotcheck_measurement ) CHARACTERISTIC ( char_plx_continuous_measurement , gBleSig_PLXContinuousMeasurement_d , ( gGattCharPropNotify_c ) ) VALUE_VARLEN ( value_PLX_continuous_measurement , gBleSig_PLXContinuousMeasurement_d , ( gPermissionNone_c ) , 20 , 3 , 0x00 , 0x00 , 0x00 ) CCCD ( cccd_PLX_continuous_measurement ) CHARACTERISTIC ( char_plx_features , gBleSig_PLXFeatures_d , ( gGattCharPropRead_c ) ) VALUE_VARLEN ( value_plx_features , gBleSig_PLXFeatures_d , ( gPermissionFlagReadable_c ) , 7 , 2 , 0x00 , 0x00 ) CHARACTERISTIC ( char_RACP , gBleSig_RaCtrlPoint_d , ( gGattCharPropIndicate_c | gGattCharPropWrite_c ) ) VALUE_VARLEN ( value_RACP , gBleSig_RaCtrlPoint_d , ( gPermissionFlagWritable_c ) , 4 , 3 , 0x00 , 0x00 , 0x00 ) CCCD ( cccd_RACP ) ‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ For more information on how to create a GATT database you can check the BLE Application Developer’s Guide chapter 7. Now we need to make the interface file that contains all the macros and declarations of the structures needed by the PLX service. Enumerated types need to be created for each of the flags field or status field of every characteristic of the service. For example, the PLX Spot-check measurement field has a flags field, so we declare an enumerated type that will help us keep the program organized and well structured. The enum should look something like this: /*! Pulse Oximeter Service - PLX Spotcheck Measurement Flags */ typedef enum { gPlx_TimestampPresent_c = BIT0 , /* C1 */ gPlx_SpotcheckMeasurementStatusPresent_c = BIT1 , /* C2 */ gPlx_SpotcheckDeviceAndSensorStatusPresent_c = BIT2 , /* C3 */ gPlx_SpotcheckPulseAmplitudeIndexPresent_c = BIT3 , /* C4 */ gPlx_DeviceClockNotSet_c = BIT4 } plxSpotcheckMeasurementFlags_tag ; ‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ The characteristics that will be indicated or notified need to have a structure type that contains all the fields that need to be transmitted to the client. Some characteristics will not always notify or indicate the same fields, this varies depending on the flags field and the requirements for each field. In order to notify a characteristic we need to check the flags in the measurement structure to know which fields need to be transmitted. The structure for the PLX Spot-check measurement should look something like this: /*! Pulse Oximeter Service - Spotcheck Measurement */ typedef struct plxSpotcheckMeasurement_tag { ctsDateTime_t timestamp ; /* C1 */ plxSpO2PR_t SpO2PRSpotcheck ; /* M */ uint32_t deviceAndSensorStatus ; /* C3 */ uint16_t measurementStatus ; /* C2 */ ieee11073_16BitFloat_t pulseAmplitudeIndex ; /* C4 */ uint8_t flags ; /* M */ } plxSpotcheckMeasurement_t ; ‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ The service has a configuration structure that contains the service handle, the initial features of the PLX Features characteristic and a pointer to an allocated space in memory to store spot-check measurements. The interface will also declare some functions such as Start, Stop, Subscribe, Unsubscribe, Record Measurements and the control point handler. /*! Pulse Oximeter Service - Configuration */ typedef struct plxConfig_tag { uint16_t serviceHandle ; plxFeatures_t plxFeatureFlags ; plxUserData_t * pUserData ; bool_t procInProgress ; } plxConfig_t ; ‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ The service source file implements the service specific functionality. For example, in the PLX service, there are functions to record the different types of measurements, store a spot-check measurement in the database, execute a procedure for the RACP characteristic, validate a RACP procedure, etc. It implements the functions declared in the interface and some static functions that are needed to perform service specific tasks. To initialize the service you use the start function. This function initializes some characteristic values. In the PLX profile, the Features characteristic is initialized and a timer is allocated to indicate the spot-check measurements periodically when the Report Stored Records procedure is written to the RACP characteristic. The subscribe and unsubscribe functions are used to update the device identification when a device is connected to the server or disconnected. bleResult_t Plx_Start ( plxConfig_t * pServiceConfig ) { mReportTimerId = TMR_AllocateTimer ( ) ; return Plx_SetPLXFeatures ( pServiceConfig - > serviceHandle , pServiceConfig - > plxFeatureFlags ) ; } ‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ All of the services implementations follow a similar template, each service can have certain characteristics that need to implement its own custom functions. In the case of the PLX service, the Record Access Control Point characteristic will need many functions to provide the full functionality of this characteristic. It needs a control point handler, a function for each of the possible procedures, a function to validate the procedures, etc. When the application makes a measurement it must fill the corresponding structure and call a function that will write the attribute in the database with the correct fields and then send an indication or notification. This function is called RecordMeasurement and is similar between the majority of the services. It receives the measurement structure and depending on the flags of the measurement, it writes the attribute in the GATT database in the correct format. One way to update a characteristic is to create an array of the maximum length of the characteristic and check which fields need to be added and keep an index to know how many bytes will be written to the characteristic by using the function GattDb_WriteAttribute(handle, index, &charValue[0]). The following function shows an example of how a characteristic can be updated. In the demo the function contains more fields, but the logic is the same. static bleResult_t Plx_UpdatePLXContinuousMeasurementCharacteristic ( uint16_t handle , plxContinuousMeasurement_t * pMeasurement ) { uint8_t charValue [ 20 ] ; uint8_t index = 0 ; /* Add flags */ charValue [ 0 ] = pMeasurement - > flags ; index ++ ; /* Add SpO2PR-Normal */ FLib_MemCpy ( & charValue [ index ] , & pMeasurement - > SpO2PRNormal , sizeof ( plxSpO2PR_t ) ) ; index + = sizeof ( plxSpO2PR_t ) ; /* Add SpO2PR-Fast */ if ( pMeasurement - > flags & gPlx_SpO2PRFastPresent_c ) { FLib_MemCpy ( & charValue [ index ] , & pMeasurement - > SpO2PRFast , sizeof ( plxSpO2PR_t ) ) ; index + = sizeof ( plxSpO2PR_t ) ; } return GattDb_WriteAttribute ( handle , index , & charValue [ 0 ] ) ; } ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ ‍ The app.c handles the application specific functionality. In the PLX demo it handles the timer callback to make a PLX continuous measurement every second. It handles the key presses and makes a spot-check measurement each time the SW3 pushbutton is pressed. The GATT server callback receives an event when an attribute is written, and in our application the RACP characteristic is the only one that can be written by the client. When this event occurs, we call the Control Point Handler function. This function makes sure the indications are properly configured and check if another procedure is in progress. Then it calls the Send Procedure Response function, this function validates the procedure and calls the Execute Procedure function. This function will call one of the 4 possible procedures. It can call Report Stored Records, Report Number of Stored Records, Abort Operation or Delete Stored Records. When the project is running, the 4 LEDs will blink indicating an idle state. To start advertising, press the SW4 button and the LED1 will start flashing. When the device has connected to a client the LED1 will stop flashing and turn on. To disconnect the device, hold the SW4 button for some seconds. The device will return to an advertising state. In this demo, the spot-check measurement is made when the SW3 is pressed, and the continuous measurement is made every second. The spot-check measurement can be stored by the application if the Measurement Storage for spot-check measurements is supported (bit 2 of Supported Features Field in the PLX Features characteristic). The RACP characteristic lets the client control the database of the spot-check measurements, you can request the existing records, delete them, request the number of stored records or abort a procedure. To test the demo you can download and install a BLE Scanner application to your smartphone that supports BLE. Whit this app you should be able to discover the services in the sensor and interact with each characteristic. Depending on the app that you installed, it will parse known characteristics, but because the PLX profile is relatively new, these characteristics will not be parsed and the values will be displayed in a raw format. In Figure 1, the USB-KW40Z was used with the sniffer application to analyze the data exchange between the PLX sensor and the client. You can see how the sensor sends the measurements, and how the client interacts with the RACP characteristic. Figure 1. Sniffer log from USB-KW40Z
View full article
I´m going to explain how configure the RTC_CLKOUT pin and the different outputs that you can get with the KW40Z board. First it must be clear that the next configuration are based to use any demo of the KW40Z_Connectivity_Software_1.0.1 and also must to use the IAR Embedded Workbench . Now that you have all the software installed follow the next instructions. Configure the pin In the Reference Manual you will realize that each pin has different ways to configure it, in our case the pin that we are going to use is the PTB3 with a MUX = 7. The mux 7 is the RTC_CLKOUT. Figure 1. PTB3 mux configuration The KSDK have many functions that initializes the ports and the different peripherals. The configure_rtc_pins() function initialize the RTC_CLKOUT pin, you can find it in the pin_mux.h file. You must add the two functions in the hardware_init() function, that is declared in hardware_init.c file. The hardware_init() function must be like show next: void hardware_init(void) {      ...      ...      NV_ReadHWParameters(&gHardwareParameters); configure_rtc_pins(0); } Enable the RTC module. Now that the pin is already configure, you have to initialize the RTC module and the 32 KHz oscillator. You must understand that the RTC module can work with different clock sources (LPO,EXTAL_32K and OSC32KCLK) and it can be reflected through the RTC_CLKOUT pin. The register that change the clock source is the SIM_SOPT1 with OSC32KOUT(17-16) and OSC32KSEL(19-18) these are the names of the register bits. The OSC32KOUT(17-16) enable/disable the output of ERCLK32K on the selected pin in our case is the PTB3. You can configure with two options. 00     ERCLK32K is not output. 01     ERCLK32K is output on PTB3. The OSC32KSEL(19-18) selects the output clock, they have 3 option like show in the next image. Figure 2. Mux of the register SIM_SOPT1 The follow table show the different outputs that you can get in the RTC_CLKOUT pin, you only have to modify the OSC32KOUT and OSC32KSEL in the register SIM_SOPT1. Figure 3. Output of RTC_CLKOUT pin. Like the configuration of the pin, KSDK have function that initialize the RTC module and the 32 KHz oscillator. The RTC_DRV_Init(0) function initialize the RTC module and is declared in fsl_rtc_driver.h file, the BOARD_InitRtcOsc() function enable the RTC oscillator and is in the board.h file, the RTC_HAL_EnableCounter() enable the TCE(Timer Counter Enable) that is in the fsl_rtc_hal.h file and finally the SIM_SOPT1_OSC32KOUT() enable/disable the ERCLK32K for the RTC_CLKOUT(PTB3) and SIM_SOPT1_OSC32KSEL() selects the output clock. To enable the RTC module copy the next code: RTC_Type *rtcBase = g_rtcBase[0];//The RTC base address BOARD_InitRtcOsc(); RTC_DRV_Init(0); RTC_HAL_EnableCounter(rtcBase, true); SIM_SOPT1 = SIM_SOPT1_OSC32KOUT(0)|SIM_SOPT1_OSC32KSEL(0);      //Your RTC_CLKOUT is 1Hz with this configuration NOTE: Don’t forget to add the header necessary in the file that you are using. Enjoy it! :smileygrin:
View full article
For this example, the BLE stack VERSION was configure to create a Custom Profile with the KW40Z . The Custom to create is the Humidity Sensor and is based on the Temperature Sensor. The First thing to know is that the Generic Attribute Profile (GATT) establishes in detail how to exchange all profile and user data over a BLE connection. GATT deals only with actual data transfer procedures and formats. All standard BLE profiles are based on GATT and must comply with it to operate correctly. This makes GATT a key section of the BLE specification, because every single item of data relevant to applications and users must be formatted, packed, and sent according to the rules. GATT defines two roles: Server and Client. The GATT server stores the data transported over the Attribute Protocol (ATT) and accepts Attribute Protocol requests, commands and confirmations from the GATT client. The GATT client accesses data on the remote GATT server via read, write, notify, or indicate operations.    Figure 1. GATT Client-Server       GATT Database establishes a hierarchy to organize attributes. These are the Profile, Service, Characteristic and Descriptor. Profiles are high level definitions that define how services can be used to enable an application and Services are collections of characteristics. Descriptors are defined attributes that describe a characteristic value. To define a GATT Database several macros are provided by the GATT_DB API. Figure 2. GATT database      To know if the Profile or service is already defined on the specification, you have to look for on Bluetooth SIG profiles and check on the ble_sig_define module if is already declared on the code. In our case the Service is not declared(because is a Custom Profile) but the characteristic of the humidity it is on the specification but not on ble_sig_define. /*! Humidity Charactristic UUID */ #define gBleSig_Humidity_d                      0x2A6F The Humidity Sensor is going to have the GATT Server, because is going to be the device that has all the information for the GATT Client. The Application works like the Temperature Sensor, every time that you press the SW1 on USB is going to send the value. On the Temperature Sensor demo have the Battery Service and Device Information, so you only have to change the Temperature Service to Humidity Service. Figure 3. GATT database of Humidity Sensor      First thing to do is define the Humidity Server that has 16 bytes. To define a new Server or a Characteristic is in gatt_uuid128.h which is located in the application folder. All macros, function or structure in SDK have a common template which helps the application to act accordingly. /* Humidity */ UUID128(uuid_service_humidity, 0xfe ,0x34 ,0x9b ,0x5f ,0x80 ,0x00 ,0x00 ,0x80 ,0x00 ,0x10 ,0x00 ,0x02 ,0x00 ,0xfa ,0x10 ,0x10)      All the Service and Characteristics is declared in gattdb.h. Descriptors are declared after the Characteristic Value declaration but before the next Characteristic declaration. In this case the permission is the CharPresFormatDescriptor that have specific description by the standard. The Units of the Humidity Characteristic is on Percentage that is 0x27AD. Client Characteristic Configuration Descriptor(CCCD) is a descriptor where clients write some of the bits to activate Server notifications and/or indications PRIMARY_SERVICE_UUID128(service_humidity, uuid_service_humidity) CHARACTERISTIC(char_humidity, gBleSig_Humidity_d, (gGattCharPropNotify_c)) VALUE(value_humidity, gBleSig_Humidity_d, (gPermissionNone_c), 2, 0x00, 0x25) DESCRIPTOR(desc_humidity, gBleSig_CharPresFormatDescriptor_d, (gPermissionFlagReadable_c), 7, 0x0E, 0x00, 0xAD, 0x27, 0x00, 0x00, 0x00) CCCD(cccd_humidity)      After that, create a folder humidity in the next path C:\....\KW40Z_BLE_Software_1.1.2\ConnSw\bluetooth\profiles. Found the temperature folder, copy the temperature_service and paste inside of the humidity folder with another name (humidity_service) Then go back and look for the interface folder, copy temperature_interface and change the name (humidity_interface) in the same path.      On the humidity_interface file should have the following code. The Service structure has the service handle, and the initialization value. /*! Humidity Service - Configuration */ typedef struct humsConfig_tag {     uint16_t serviceHandle;     int16_t initialHumidity;        } humsConfig_t; The next configuration structure is for the Client; in this case we don’t need it. /*! Humidity Client - Configuration */ typedef struct humcConfig_tag {     uint16_t    hService;     uint16_t    hHumidity;     uint16_t    hHumCccd;     uint16_t    hHumDesc;     gattDbCharPresFormat_t  humFormat; } humcConfig_t;      At minimum on humidity_service file, should have the following code. The service stores the device identification for the connected client. This value is changed on subscription and non-subscription events. /*! Humidity Service - Subscribed Client*/ static deviceId_t mHums_SubscribedClientId;      The initialization of the service is made by calling the start procedure. This function is usually called when the application is initialized. In this case is on the BleApp_Config(). On stop function, the unsubscribe function is called. bleResult_t Hums_Start (humsConfig_t *pServiceConfig) {        mHums_SubscribedClientId = gInvalidDeviceId_c;         return Hums_RecordHumidityMeasurement (pServiceConfig->serviceHandle, pServiceConfig->initialHumidity); } bleResult_t Hums_Stop (humsConfig_t *pServiceConfig) {     return Hums_Unsubscribe(); }      Depending on the complexity of the service, the API will implement additional functions. For the Humidity Sensor only have a one characteristic. The measurement will be saving on the GATT database and send the notification to the client. This function will need the service handle and the new value as input parameters. bleResult_t Hums_RecordHumidityMeasurement (uint16_t serviceHandle, int16_t humidity) {     uint16_t handle;     bleResult_t result;     bleUuid_t uuid = Uuid16(gBleSig_Humidity_d);         /* Get handle of Humidity characteristic */     result = GattDb_FindCharValueHandleInService(serviceHandle,         gBleUuidType16_c, &uuid, &handle);     if (result != gBleSuccess_c)         return result;     /* Update characteristic value */     result = GattDb_WriteAttribute(handle, sizeof(uint16_t), (uint8_t*)&humidity);     if (result != gBleSuccess_c)         return result; Hts_SendHumidityMeasurementNotification(handle);     return gBleSuccess_c; }      After save the measurement on the GATT database with GattDb_WriteAttribute function we send the notification. To send the notification, first have to get the CCCD and after check if the notification is active, if is active send the notification. static void Hts_SendHumidityMeasurementNotification (   uint16_t handle ) {     uint16_t hCccd;     bool_t isNotificationActive;     /* Get handle of CCCD */     if (GattDb_FindCccdHandleForCharValueHandle(handle, &hCccd) != gBleSuccess_c)         return;     if (gBleSuccess_c == Gap_CheckNotificationStatus         (mHums_SubscribedClientId, hCccd, &isNotificationActive) &&         TRUE == isNotificationActive)     {           GattServer_SendNotification(mHums_SubscribedClientId, handle);     } }      Steps to include the files into the demo. 1. Create a clone of the Temperature_Sensor with the name of Humidity_Sensor 2. Unzip the Humidity_Sensor folder. 3. I n the fallowing path < kw40zConnSoft _intall_dir> \ConnSw\bluetooth\profiles\interface save the humidity_interface file . 4. In the <kw40zConnSoft_intall_dir> \ConnSw\ bluetooth \profiles save the humidity folder 5. I n the next directory < kw40zConnSoft _intall_dir> \ConnSw\examples\bluetooth\humidity_sensor\common replaces with the common folder.           Steps to include the paths into the demo using IAR Embedded Workbench​ Once you already save the folders in the corresponding path you must to indicate in the demo where are they. 1. D ra g the files into the corresponding folder. The principal menu is going to see like this. Figure 4. Principal Menu 2. Then click Option Figure 5. Option 3. Click on the C/C++ Compiler and then on the Preprocessor     Figure 6. Preposcessor Window 4. After that click on  "..." button to edit the include directories and then click to add a new path.      Add the <kw40zConnSoft_intall_dir> \ConnSw\bluetooth \profile\humidity path. Figure 7. Add a path Finally compile and enjoy the demo! NOTE: If you want to probe the demo using another board you must to run the humidity_collector demo too. Figure 8. Example of the Humidity Sensor using the Humidity Collector demo.
View full article
OVERVIEW This document shows how to include the PowerLib to enable low power functionality in connectivity software projects that does not include it. It shows step by step instructions on how to import, configure and use this module. ADD POWER LIBRARY INTO A NEW PROJECT Once you have installed the “Connectivity Software” package, browse for the extracted files (typically located in C:\Freescale\KW40Z_Connectivity_Software_1.0.0). In this location search for the LowPower folder, then copy and paste it into your new project folder. Open your IAR project and create a new group called “Low Power”. Inside this group add two new groups called “Interface” and “Source”. In the Windows explorer, open the LowPower folder copied in the previous step. Drag and drop the contents of the "Interface" folder to the "Interface" group in IAR. Do the same for the "Source" folder. You can also use the option "Add Files" in the group menu to add the files. Note: Do not copy the “PWR_Platform.c” and “PWR_Platform.h” files. Once you have copied the files in their respective folders, you need to add the paths of these files in the project environment. Right click on the project name and select "Options". In Options go to “C/C++Compiler”, select “Preprocessor” and click on the red square. The next window will appear. Click on <Click to add>  to open the windows explorer. Navigate to the folder PowerLib/Interface in your project to add the "Interface" folder path. Repeat this step with the "Source" folder. HOW TO CONFIGURE LOW POWER To use low power in your project you need to define the following macros in the “app_preinclude.h” file: /* Enable/Disable PowerDown functionality in PwrLib */ #define cPWR_UsePowerDownMode           1 /* Enable/Disable BLE Link Layer DSM */ #define cPWR_BLE_LL_Enable              1 /* Default Deep Sleep Mode*/ #define cPWR_DeepSleepMode              4 cPWR_UsePowerDownMode enables the necessary functions to use low power in your project. cPWR_BLE_LL_Enable configures the link layer to work in doze mode when in low power, and cPWR-DeepSleepMode defines the deep sleep mode the MCU will enter when the low power function is executed. There are the six different modes that can be used.   Mode 1: MCU/Radio low power modes:         MCU in LLS3 mode.         BLE_LL in DSM.       Wakeup sources:       GPIO (push button) interrupt using LLWU module.        BLE_LL wake up interrupt(BLE_LL reference clock reaches wake up instance register)  using LLWU module.              - BTE_LL wakeup timeout: controlled by the BLE stack(SoC must be awake before next BLE action).              - BTE_LL reference clock source:   32Khz oscillator              - BTE_LL reference clock resolution:     625us                            Mode 2: MCU/Radio low power modes:         MCU in LLS3 mode.         BLE_LL in DSM.       Wakeup sources:         GPIO (push button) interrupt using LLWU module.         BLE_LL wake up interrupt(BLE_LL reference clock reaches wake up instance register)  using LLWU module.                - BTE_LL wakeup timeout: cPWR_DeepSleepDurationMs by default. Use PWR_SetDeepSleepTimeInMs  to change it at run time. Maximum timeout is 40959 ms. BLE suppose to be idle.                - BTE_LL reference clock source:   32Khz oscillator                - BTE_LL reference clock resolution:     625us   Mode  3: MCU/Radio low power modes:         MCU in LLS3 mode.         BLE_LL in idle.       Wakeup sources:        GPIO (push button) interrupt using LLWU module.        DCDC PowerSwitch - available in buck mode only.        LPTMR interrupt using LLWU module           - LPTMR wakeup timeout: cPWR_DeepSleepDurationMs by default. Use PWR_SetDeepSleepTimeInMs to change it at run time. Maximum timeout is 65535000 ms (18.2 h).           - LPTMR clock source:   32Khz oscillator           - LPTMR resolution:     modified at run time to meet timeout value. Mode 4: MCU/Radio low power modes:         MCU in VLLS0/1 mode(VLLS0 if DCDC bypassed/ VLLS1 otherwise ).        BLE_LL in idle.       Wakeup sources:        GPIO (push button) interrupt using LLWU module.         DCDC PowerSwitch - available in buck mode only. Mode 5: MCU/Radio low power modes:        MCU in VLLS2 (4k Ram retention (0x20000000- 0x20000fff)).        BLE_LL in idle.       Wakeup sources:         GPIO (push button) interrupt using LLWU module.         DCDC PowerSwitch - available in buck mode only.   Mode 6: MCU/Radio low power modes:         MCU in STOP.       Wakeup sources:         GPIO (push button) interrupt using LLWU module.         DCDC PowerSwitch - available in buck mode only.         LPTMR wakeup timeout: cPWR_DeepSleepDurationMs by default. Use PWR_SetDeepSleepTimeInMs to change it at run time. Maximum timeout is 65535000 ms (18.2 h).          - LPTMR clock source:   32Khz oscillator           - LPTMR resolution:     modified at run time to meet timeout value.           - LPTMR resolution:     modified at run time to meet timeout value.         Radio interrupt LL or 802.15.4         UART Configuring Wakeup Source The PowerLib software includes preconfigured wakeup methods for low power. These methods are described below and a couple of examples are included. From Reset: Comming from Reset From PSwitch_UART: Wakeup by UART interrupt From KeyBoard: Wakeup by TSI/Push button interrupt From LPTMR: Wakeup by LPTMR timer interrupt From Radio:  Wakeup by RTC timer interrupt From BLE_LLTimer:  Wakeup by BLE_LL Timer DeepSleepTimeout:  DeepSleep timer overflow. SleepTimeout: Sleep timer overflow. Configure Module Wakeup using LPTMR This example explains how to configure the third deep sleep mode using the LPTMR as wakeup source. The desired low power mode must be configured in the file app_preinclude.h. /* Default Deep Sleep Mode*/ #define cPWR_DeepSleepMode            3 On the same file, the macro cPWR_DeepSleepDurationMs macro must be added. It defines the time the MCU will be in low power mode before being waken by the low power timer. By default it it set to 10 seconds (10000 milliseconds). #define cPWR_DeepSleepDurationMs     10000 This defines the time that the device will remain asleep by default. The PWR_SetDeepSleepTimeInMs function can be used to change this period at run time. Consider that the maximum time period is 65535000 ms (18.2 hours). PWR_SetDeepSleepTimeInMs(10000); Also the deep sleep mode can be changed at run time with the following function. PWR_ChangeDeepSleepMode(3); For further power reduction, all the modules not in use must be turned off . To run in this mode, all the timers except the LPTMR must be turned off. The device enters in low power mode with the following code lines in the main application. PWR_SetDeepSleepTimeInMs(cPWR_DeepSleepDurationMs); PWR_ChangeDeepSleepMode(3); PWR_AllowDeviceToSleep(); Configure GPIO (Push Button) wakeup. In the “PWRLib.c” file, find the “PWRLib_Init” function. It contains the code to initialize the LLWU pins to be used for wakeup. Chip configuration Reference Manual chapter contains information on which LLWU pins are tied to GPIOs on the MCU. For this example LLWU pins 6 and 7 (which are tied to PTA18 and PTA19 in the MCU) are used.   LLWU_PE1 = 0x00;   LLWU_PE2 = LLWU_PE2_WUPE7(0x03) | LLWU_PE2_WUPE6(0x03);   LLWU_PE3 = 0x00;   LLWU_PE4 = 0x00; Since the LLWU pin sources work as GPIO interrupts, the propper ports in the MCU must be configured. Following code shows howthese pins are configured in the MCU.   /* PORTA_PCR18: ISF=0,MUX=1 */   PORTA_PCR18 = (uint32_t)((PORTA_PCR18 & (uint32_t)~(uint32_t)(                                                                 PORT_PCR_ISF_MASK |                                                                   PORT_PCR_MUX(0x06)                                                                     )) | (uint32_t)(                                                                                     PORT_PCR_MUX(0x01)                                                                                       ));   PORTA_PCR19 = (uint32_t)((PORTA_PCR19 & (uint32_t)~(uint32_t)(                                                                 PORT_PCR_ISF_MASK |                                                                   PORT_PCR_MUX(0x06)                                                                     )) | (uint32_t)(                                                                                     PORT_PCR_MUX(0x01)                                                                                       )); Once the pins have been defined, it is neccesary to configure them as Keyboard inputs for the Power Lib. Go to "PWRLib.h" and find the next define: #define  gPWRLib_LLWU_KeyboardFlagMask_c (gPWRLib_LLWU_WakeupPin_PTA18_c | gPWRLib_LLWU_WakeupPin_PTA19_c ) In this define you must place the pins that were configured previously as wakeup sources. Using Low Power in the Project When you define "cPWR_UsePowerDownMode"  in app_preinclude.h, it automatically creates a task in "ApplMain.c" called "App_Idle_Task". When executed by the OS scheduler, this task verifies if the device can go to sleep. This statement is always false unless the next function is called. PWR_AllowDeviceToSleep(); This function indicates the program that the device can enter in low power and will execute the neccesary code to enter in the power mode configured at that time. Note: Before you allow the device to sleep, disable all uneccessary modules and turn off all leds. When the device is ready to enter in low power (all the application layers allows it and the device is in an iddle state) function PWR_EnterLowPower() must be called. This function will enter the MCU into the selected low power mode. On the HID example this is done into the iddle task as shown below. #if (cPWR_UsePowerDownMode) static void App_Idle(void) {     PWRLib_WakeupReason_t wakeupReason;         if( PWR_CheckIfDeviceCanGoToSleep() )     {         /* Enter Low Power */         wakeupReason = PWR_EnterLowPower(); #if gFSCI_IncludeLpmCommands_c         /* Send Wake Up indication to FSCI */         FSCI_SendWakeUpIndication(); #endif #if gKeyBoardSupported_d              /* Woke up on Keyboard Press */         if(wakeupReason.Bits.FromKeyBoard)         {             KBD_SwitchPressedOnWakeUp();             PWR_DisallowDeviceToSleep();         } #endif                  if(wakeupReason.Bits.DeepSleepTimeout)         {           Led1On();           for(;;)           {}         }     } } #endif /* cPWR_UsePowerDownMode */ PWR_CheckIfDeviceCanGoToSleep() function checks that all the application layers are agree on entering in low power mode (checking that PWR_DisallowDeviceToSleep() function hasn't been called). If everything is ok, function PWR_EnterLowPower() enters the device in low power and waits for a wakeup event.
View full article
As mentioned in this other post, its important to have the correct trim on the external XTAL. However, once you have found the required trim to properly adjust the frequency, it is not very practical to manually adjust it in every device. So here is where changing the default XTAL trim comes in handy. KW41Z With the KW41 Connecitivity Software 1.0.2, it is a pretty straightforward process. In the hardware_init.c file, there is a global variable mXtalTrimDefault. To change the default XTAL trim, simply change the value of this variable. Remember it is an 8 bit register, so the maximum value would be 0xFF. KW40Z With the KW40, it is a similar process; however, it is not implemented by default on the KW40 Connectivity Software 1.0.1, so it should be implemented manually, following these steps: Create a global variable in hardware_init.c to store the default XTAL trim, similar to the KW41:  /* Default XTAL trim value */ static const uint8_t mXtalTrimDefault = 0xBE ; ‍‍‍‍‍‍ ‍ ‍ Overwrite the default XTAL trim in the hardware_init() function, adding these lines after NV_ReadHWParameters(&gHardwareParameters):    if ( 0xFFFFFFFF == gHardwareParameters . xtalTrim )   {       gHardwareParameters . xtalTrim = mXtalTrimDefault ;   } ‍‍‍‍‍‍‍‍ ‍ ‍ ‍ ‍ Add this define to allow XTAL trimming in the app_preinclude.h file:  /* Allows XTAL trimming */ #define gXcvrXtalTrimEnabled_d  1‍‍‍‍‍ ‍ ‍ Once you have found the appropriate XTAL trim value, simply change it in the global variable declared in step 1.
View full article
[中文翻译版] 见附件   原文链接: https://community.nxp.com/docs/DOC-340508
View full article
[中文翻译版] 见附件   原文链接: https://community.nxp.com/docs/DOC-340993
View full article
This Application Note provides guidance on migrating ZigBee 3.0 Base device application designed for the NXP JN516x wireless microcontrollers to the KW41Z with the help of attached PDF.
View full article