2017-06-18 TM dotstack Dotstack Porting Guide. dotstack Bluetooth stack is a C library and several external interfaces that needs to be implemented in the integration layer to run the stack on a concrete platform. The interfaces that needs to be implemented are: BT controller transport BT controller identification Authentication Timers Signal processing The core library of the stack is not thread safe. Therefore, if the stack will run in a multi-threaded environment all callback function used by the above interfaces must be called from the thread that runs the stack. I.e., interrupt handlers cannot directly call callbacks. They have to use some kind of synchronization mechanism to notify the stacks task to call the callback for them. This applies to all other dotstack APIs. They have to be called from the BT thread. BT controller transport This interface allows the stack to communicate with the HCI controller. It consists of two functions: void bt oem send(const bt byte* buffer, bt uint len, bt oem send callback fp callback) void bt oem recv(bt byte* buffer, bt uint len, bt oem recv callback fp callback) The implementation of bt oem send() must send the specified number of bytes to the HCI controller and call the provided callback function. The implementation of bt oem recv() must receive the specified number of bytes from the HCI controller and call the provided callback function. The core library supports H4, 3-wire and BCSP host transports. All these transport work over UART. If USB or SDIO transport support is required, the easiest way to impmenet that is to emulate H4 transport. BT controller identification 1 2017-06-18 This interface is used to set the name and Class of device of the controller during stack initialization. The values set during initialization may later be changed with HCI APIs. The interface consists of the following functions: const char* bt oem get device name(void) bt long bt oem get device class(void) bt oem get device name() must return a string no longer than 248 characters which will be written to the controller. Other devices will see this name when they discover the controller. The name of the device can be changed after initialization by calling bt hci write local name(). bt oem get device class() must return the Class of device value which is a bitmask of values defined by the Bluetooth specification. The Class of device can be changed after initialization by calling bt hci send cmd() (this function allows to send any HCI command to the controller). Authentication This interface is used when two controllers initiated a pairing procedure. There are 2 pairing mechanisms legacy and Simple Secure Pairing (SSP). The legacy pairing uses the following function when the controller needs the host to provide it a PIN code: void bt oem get pin code(bt bdaddr t* bdaddr remote) In response to call of this function the integration layer must call either bt hci send pin code() or bt hci reject pin code(). These calls does not have to be made inside bt oem get pin code(). If the device has a display and keyboard it may show a UI to enter a PIN code first and call bt hci send pin code() later after the user has entered the PIN code. The PIN code may also be hardcoded. In this case bt oem get pin code() may simply call bt hci send pin code(). If for some reason the device should not pair with the device that support only legacy pairing bt hci reject pin code() may be used to deny pairing requests from such devices. Remember, if UI runs in a different thread, after its finished, the BT thread has to be notified (e.g., send a message to a queue) that it has to call bt hci send pin code() or bt hci reject pin code(). The SSP uses the following function: void bt oem ssp callback(SSP EVENT spp event, void* event param, void* init param) This function must implement a number of event handlers that may be sent during pairing. Our samples include an implementation of this function that implements just works association mode (i.e., no PIN code entering) along with instructions on how to implement other models. See btauth.c. The result of pairing procedure is a link key which is used to authenticate the remote device and encrypt the traffic between devices. Link keys may be saved to a non-volatile storage in order to skip pairing after the device has been power cycled. To manager link keys there are 2 functions: 2