MicroBitUtilityService - replaces PR 178

inc/MicroBitConfig.h

@@ -249,6 +249,18 @@
     #define MICROBIT_BLE_DEVICE_INFORMATION_SERVICE 1
 #endif
 
+// Enable/Disable BLE Service in pairing mode: MicroBitUtilityService
+// Set '1' to enable.
+#ifndef MICROBIT_BLE_UTILITY_SERVICE_PAIRING
+#define MICROBIT_BLE_UTILITY_SERVICE_PAIRING 1
+#endif
+
+// Enable/Disable BLE Service in application mode: MicroBitUtilityService
+// Set '1' to enable.
+#ifndef MICROBIT_BLE_UTILITY_SERVICE
+#define MICROBIT_BLE_UTILITY_SERVICE 0
+#endif
+
 // Enable/Disable Nordic Firmware style BLE based UART implimentation.
 // The default codal implimentation reverses the TX/RX ids  
 // Set to '1' to enable

inc/bluetooth/MicroBitUtilityService.h

@@ -0,0 +1,207 @@
+/*
+The MIT License (MIT)
+
+This class has been written for the Microbit Educational Foundation.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef MICROBIT_UTILITY_SERVICE_H
+#define MICROBIT_UTILITY_SERVICE_H
+
+#include "MicroBitConfig.h"
+
+#if CONFIG_ENABLED(DEVICE_BLE)
+
+#include "MicroBitBLEManager.h"
+#include "MicroBitBLEService.h"
+#include "MicroBitMemoryMap.h"
+
+#include "MicroBitFlash.h"
+#include "MicroBitStorage.h"
+
+#include "MicroBitComponent.h"
+#include "MicroBitEvent.h"
+#include "EventModel.h"
+#include "MicroBitLog.h"
+
+/* Set this to enable an alternative implementation, which creates a fiber to process requests.
+ * The default simply uses an event to trigger processing, and if processRequest() blocks,
+ * a temporary fiber is created as necessary.
+ */
+#ifndef MicroBitUtilityService_FIBER
+#define MicroBitUtilityService_FIBER 0
+#endif
+
+
+class MicroBitUtilityWorkspace;
+
+
+/**
+ * Class declration for the custom MicroBit Utility Service.
+ * Provides simple BLE request/response
+ * See MicroBitUtilityTypes.h
+ */
+class MicroBitUtilityService : public MicroBitBLEService
+{
+    static MicroBitUtilityService *shared;
+
+    public:
+    /**
+     * Return a pointer to the shared service
+     * @return a pointer to the service, or NULL if it has not been created
+     */
+    static MicroBitUtilityService *getShared()
+    {
+        return shared;
+    }
+
+    /**
+     * Return a pointer to the shared service, creating it if necessary
+     * @param _ble an instance of BLEDevice
+     * @param _messageBus An instance of a MessageBus to interface with.
+     * @param _storage A persistent storage manager to use to hold non-volatile state.
+     * @param _log a log storage manager to read stored data.
+     * @return a pointer to the service, or NULL if it has not been created
+     */
+    static MicroBitUtilityService *createShared( BLEDevice &_ble, EventModel &_messageBus, MicroBitStorage &_storage, MicroBitLog &_log);
+
+    public:
+    /**
+     * Constructor.
+     * @param _ble an instance of BLEDevice
+     * @param _messageBus An instance of a MessageBus to interface with.
+     * @param _storage A persistent storage manager to use to hold non-volatile state.
+     * @param _log a log storage manager to read stored data.
+     */
+    MicroBitUtilityService( BLEDevice &_ble, EventModel &_messageBus, MicroBitStorage &_storage, MicroBitLog &_log);
+
+    private:
+    /**
+     * Invoked when BLE connects.
+     * Start listening for events
+    */
+    void onConnect( const microbit_ble_evt_t *p_ble_evt);
+
+    /**
+     * Invoked when BLE disconnects.
+     * Stop listening for events
+    */
+    void onDisconnect( const microbit_ble_evt_t *p_ble_evt);
+
+    /**
+     * Callback. Invoked when any of our attributes are written via BLE.
+     * Record the  request, and trigger processing.
+     * Requests are not queued. If a request is actively being processed, ignore the new request, otherwise simply override the previous one.
+     */
+    void onDataWritten(const microbit_ble_evt_write_t *params);
+
+    /**
+     * Callback. Invoked when a registered event occurs.
+     */
+    void onEvent(MicroBitEvent e);
+
+    private:
+    // MessageBus we're using
+    EventModel          &messageBus;
+    MicroBitStorage     &storage;
+    MicroBitLog         &log;
+
+    uint8_t characteristicValue[ 20];
+
+    // Index for each charactersitic in arrays of handles and UUIDs
+    typedef enum mbbs_cIdx
+    {
+        mbbs_cIdxCTRL,
+        mbbs_cIdxCOUNT
+    } mbbs_cIdx;
+
+    // UUIDs for our service and characteristics
+    static const uint16_t serviceUUID;
+    static const uint16_t charUUID[ mbbs_cIdxCOUNT];
+
+    // Data for each characteristic when they are held by Soft Device.
+    MicroBitBLEChar      chars[ mbbs_cIdxCOUNT];
+
+    public:
+    int              characteristicCount()          { return mbbs_cIdxCOUNT; };
+    MicroBitBLEChar *characteristicPtr( int idx)    { return &chars[ idx]; };
+
+    private:
+
+    MicroBitUtilityWorkspace *workspace;
+
+    /**
+     * Listen for or ignore  events for processing requests
+     * @param yes true to listen, otherwise ignore
+     */
+    void listen( bool yes);
+
+    /**
+     * Send a reply packet
+     * @param data Data to send
+     * @param length Length if the data
+     * @return DEVICE_OK if sent
+     */
+    int sendReply( const void *data, uint16_t length);
+
+    /**
+     * Process the current request. This may block.
+     * @return DEVICE_OK if finished
+     */
+    int processRequest();
+
+    /**
+     * Process request typeLogLength
+     * @return DEVICE_OK if finished
+     */
+    int processLogLength();
+
+    /**
+     * Process request typeLogRead
+     * @return DEVICE_OK if finished
+     */
+    int processLogRead();
+
+#if MicroBitUtilityService_FIBER
+    volatile int8_t fiberActive;
+    volatile bool   fiberExists;
+
+    /**
+     * Keep the fiber running or create a new one
+     */
+    void ensureFiber();
+
+    /**
+     * Callback invoked when the fiber exits
+     * @param param Pointer to the MicroBitUtilityService
+     */
+    static void fiberComplete( void *param);
+
+    /**
+     * Fiber to process requests, which releases itself after a period of inactivity
+     * @param param Pointer to the MicroBitUtilityService
+     */
+    static void fiberEntry( void *param);
+#endif
+};
+
+
+#endif
+#endif

inc/bluetooth/MicroBitUtilityTypes.h

@@ -0,0 +1,115 @@
+/*
+The MIT License (MIT)
+
+This header has been written for the Microbit Educational Foundation.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef MICROBIT_UTILITY_TYPES_H
+#define MICROBIT_UTILITY_TYPES_H
+
+#include <stdint.h>
+
+/* Define types for the MicroBitUtilityService
+ *
+ * request_t  - Request sent from client to service.
+ *              job   (1 byte)          - see below
+ *              type  (1 byte)          - specifies the request type
+ *              data  (up to 18 bytes)  - depends on request type
+ *
+ * reply_t    - Reply from service to client.
+ *              job   (1 byte)          - see below
+ *              data  (up to 19 bytes)  - depends on request type
+ *
+ * job        - Synchronize requests and replies.
+ *              Enables the client to ignore replies to a previous request, and detect missing reply packets.
+ *              Client cycles high nibble i.e. { 0x00, 0x10, 0x20, ..., 0xF0, 0x00, ...}
+ *              Service reply cycles low nibble, i.e client job + { 0x00, 0x01, 0x02, ..., 0x0E, 0x00, ... }
+ *              low nibble == 0x0F (jobLowERR) in a reply indicates error (data = 4 bytes signed integer error)
+ *
+ * Request types and data contents:
+ *
+ * type 1     - Log file length
+ * request      format    (1 byte)          - 0 = HTML header; 1 = HTML; 2 = CSV
+ * reply        length    (4 bytes)         - unsigned integer log data length
+ *
+ * type 2     - Log file data
+ * request      format    (1 byte)          - 0 = HTML header; 1 = HTML; 2 = CSV
+ *              reserved  (1 byte)          - set to zero
+ *              index     (4 bytes)         - unsigned integer index into file
+ *              batchlen  (4 bytes)         - unsigned size in bytes to return
+ *              length    (4 bytes)         - length of whole file, from request type 1 (Log file length)
+ * reply        data      (up to 19 bytes)  - 1 or more reply packets, to total batchlen bytes
+ *
+ */
+namespace MicroBitUtility
+{
+    typedef enum requestType_t
+    {
+        requestTypeNone,
+        requestTypeLogLength,           // reply data = 4 bytes log data length
+        requestTypeLogRead              // reply data = up to 19 bytes of log data
+    } requestType_t;
+
+    typedef struct request_t
+    {
+        uint8_t  job;                   // Client cycles high nibble i.e. { 0x00, 0x10, 0x20, ..., 0xF0, 0x00, ...}
+        uint8_t  type;                  // requestType_t
+        uint8_t  data[18];
+    } request_t;
+
+    typedef struct reply_t
+    {
+        uint8_t  job;                   // Service cycles low nibble i.e client job + { 0x00, 0x01, 0x02, ..., 0x0E, 0x00, ... }
+                                        // low nibble == 0x0F (jobLowERR) indicates error and data = 4 bytes signed integer error
+        uint8_t  data[19];
+    } reply_t;
+
+    typedef enum requestLogFormat
+    {
+        requestLogHTMLHeader = 0,
+        requestLogHTML = 1,
+        requestLogCSV = 2
+    } requestLogFormat;
+
+    typedef struct requestLog_t
+    {
+        uint8_t  job;
+        uint8_t  type;                  // requestType_t
+        uint8_t  format;                // requestLogFormat
+    } requestLog_t;
+
+    typedef struct requestLogRead_t
+    {
+        uint8_t  job;
+        uint8_t  type;                  // requestType_t
+        uint8_t  format;                // requestLogFormat
+        uint8_t  reserved;              // set to zero
+        uint32_t index;                 // index into data
+        uint32_t batchlen;              // size in bytes to return
+        uint32_t length;                // length of whole file, from requestTypeLogLength
+    } requestLogRead_t;
+
+    const uint8_t jobLowMAX = 0x0E;
+    const uint8_t jobLowERR = 0x0F;     // reply data = 4 bytes signed integer error
+};
+
+
+#endif

inc/compat/MicroBitCompat.h

@@ -372,6 +372,8 @@ const uint16_t MICROBIT_ID_MBED_TICKER       __attribute__ ((deprecated)) = 83;
 
 #define MICROBIT_ID_LOG                                         DEVICE_ID_LOG
 
+#define MICROBIT_ID_UTILITY                                     45
+
 #define MICROBIT_MAXIMUM_HEAPS                                  DEVICE_MAXIMUM_HEAPS
 #define MICROBIT_NESTED_HEAP_SIZE                               0
 #define MICROBIT_PANIC_HEAP_FULL                                DEVICE_PANIC_HEAP_FULL

model/MicroBit.cpp

@@ -253,6 +253,11 @@ int MicroBit::init()
             // Start the BLE stack, if it isn't already running.
             bleManager.init( ManagedString( microbit_friendly_name()), getSerial(), messageBus, storage, true);
 
+
+#if CONFIG_ENABLED(MICROBIT_BLE_UTILITY_SERVICE_PAIRING)
+            MICROBIT_DEBUG_DMESG( "UTILITY_SERVICE");
+            MicroBitUtilityService::createShared( *ble, messageBus, storage, log);
+#endif
             // Enter pairing mode, using the LED matrix for any necessary pairing operations
             bleManager.pairingMode(display, buttonA);
         }
@@ -262,6 +267,11 @@ int MicroBit::init()
 #if CONFIG_ENABLED(DEVICE_BLE) && CONFIG_ENABLED(MICROBIT_BLE_ENABLED)
     // Start the BLE stack, if it isn't already running.
     bleManager.init( ManagedString( microbit_friendly_name()), getSerial(), messageBus, storage, false);
+
+#if CONFIG_ENABLED(MICROBIT_BLE_UTILITY_SERVICE)
+    MICROBIT_DEBUG_DMESG( "UTILITY_SERVICE");
+    MicroBitUtilityService::createShared( *ble, messageBus, storage, log);
+#endif
 #endif
 
     // Deschedule for a little while, just to allow for any components that finialise initialisation

model/MicroBit.h

@@ -84,6 +84,7 @@ DEALINGS IN THE SOFTWARE.
 #include "MicroBitTemperatureService.h"
 #include "MicroBitUARTService.h"
 #include "MicroBitPartialFlashingService.h"
+#include "MicroBitUtilityService.h"
 #endif
 
 #include "MicroBitStorage.h"