Overview

This provides an API for interacting with the micro:bit's log over Bluetooth via WebBLE. It also includes a demo application to show how it works.

Files / Manifest

ubitwebblelog.js: The actual API (the only file needed for other applications)
Demo application (a web-based console that shows the different messages)
- index.html: HTML with in-line JavaScript for the application
  - View Live Version Only works in Chrome
  - View Local Live Version Only works in Chrome
- style.css
- Requires ubitwebblelog.js
Documentation files
- readme.md: Overview of project
- docs: Directory including JSDoc documentation
  - jsdoc.md: Initial page / readme for JSDocs
- _config.yml: GitHub pages config
- LICENSE: MIT License

Micro:bit configuration

Go to https://makecode.microbit.org/
Create a new project
Add the BLELog extension
- - Extensions
- Paste the URL: https://github.com/bsiever/pxt-blelog in the search field and hit enter
- Click on the tile to add the extension.
- You'll asked to confirm removal of the radio blocks (and add this extension). Click on the Remove ... button.
Add the Data Logger Bluetooth's bluetooth data logger service to the on start handler
Add data logger's set columns to the on start handler too.
- Add in the names of the fields (columns)
Add other handlers that support data points and/or erasing the log.

input.onButtonPressed(Button.A, function () {
    datalogger.log(
    datalogger.createCV("x", input.acceleration(Dimension.X)),
    datalogger.createCV("y", input.acceleration(Dimension.Y))
    )
})
input.onButtonPressed(Button.AB, function () {
    datalogger.deleteLog(datalogger.DeleteType.Fast)
})
blelog.startBLELogService()
datalogger.setColumnTitles(
"x",
"y"
)

Program the Micro:bit from Shared Project

Example Project: https://makecode.microbit.org/_TDy4WzCU3iJM

API

Objects

uBitManager: A single uBitManager should be created for any application. It is used to connect to and manage available micro:bit data loggers. All events for individual micro:bits are sent via the manager.
uBit: A single micro:bit object. It provides operations to change its label, refresh all it's data, remove it, etc.

A typical application will:

Create a single uBitManager instance.
Register with it for events of interest.
Allow users to call the uBitManager's connect() to connect to micro:bit data loggers.
Allow interactions via:
- Responding to any incoming events (i.e., graph or log data)
- Allowing users to call operations on individual micro:bits (refresh() data, erase(), etc.)

Class Diagrams

classDiagram
    class uBitManager {
      +(async) void  connect()
      +Map(any:uBit) getDevices() 
    }

    class uBit {
      +void  disconnect()
      +string getLabel()
      +void setLabel()
      +[string] getCSV()
      +[string] getRawCSV()
      +[string] getHeaders()
      +[[string]] getData(start, end)
      +int getDataLength()
      +void sendErase()
      +void sendAuthorization(string)
      +void refreshData()
      +void remove()
    }

    uBitManager "1" *-- "*" uBit

    %%link uBitManager "./docs/docs/uBitManager.html" "Link"
    %%link uBit "./docs/docs/uBit.html" "Link"

Connection Process

Checking Password

If a password is not needed or a successful password is already saved, after connection it will proceed on to retrieve all new data (After Security Confirmation process). Otherwise the sendAuthorization() must be used to send a password to get access.

flowchart TD
  id0([Connected])
  id1{Check security}
  id4([After Security Confirmation])
  id5[Send event: unauthorized]
  id6[sendAuthorization]

  id0-->id1
  id1-- Authorized -->id4
  id1-- Unauthorized -->id5
  id5-->id6
  id6-->id1

After Security Confirmation

After gaining authorization to access data, the data that was acquired since the last connection is retrieved.

flowchart TD
  id0([After Security Confirmation])
  id1[Request all new data since last connection]
  id2[Wait for chunk of data]
  id3[Process chunk of data]
  id4[Send event: progress]
  id4b["Send events: row-updated (multiple)"]
  id5{Done getting data?}
  id6[Send event: data-ready]

  id0-->id1
  id1-->id2
  id2-->id3
  id3-->id4
  id4-->id4b
  id4b-->id5
  id5-- No -->id2
  id5-- Yes -->id6

Multiple progress and row-updated events will occur while data is being retrieved. The UTC timestamps will not be known until all data has been retrieved (after data-ready).

An approach for graphing

flowchart TD
  id0([After Connect])
  id1[Wait for data-ready]
  id2[Graph all existing data]
  id3[Add listener for row-update]
  id4[Wait for row-update]
  id5["Update graph with new row(s)"]
  
  id0-->id1
  id1-->id2
  id2-->id3
  id3-->id4
  id4-->id5
  id5-->id4

Sequences

Connection

sequenceDiagram
  participant Front end
  participant uBitManager 

Front end ->>+uBitManager: connect()
loop Until all new data received
  uBitManager -->>Front end: Event:progress
  loop Each updated row
  uBitManager -->>Front end: Event:row-updated
  end
end
uBitManager -->>Front end: Event: data-ready

Security access

sequenceDiagram
  participant Front end
  participant uBitManager 

Front end ->>uBitManager: connect()
uBitManager -->>Front end: Event: unauthorized
Front end ->>uBitManager: sendAuthorization()

If the password is invalid there will be another unauthorize event. Otherwise it will proceed to retrieve data from the micro:bit.

JSDocs: Documentation on the functions

JSDocs Here

Regenerate

jsdoc ubitwebblelog.js -r jsdoc.md -d docs

Example

See index.html for a complete example application.

TODO Log

Finish docs / sequence diagrams
Finish testing persistent storage and enable it.
More testing.
- Multiple devices: Seems good
Try to speed up initial download:
- https://punchthrough.com/ble-throughput-part-4/
Note that headers must include "Time" and unit of time must be seconds

bsiever / microbit-webblelog