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 VersionOnly works in Chrome
    • View Local Live VersionOnly 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:

1. Create a single uBitManager instance.
2. Register with it for events of interest.
3. Allow users to call the uBitManager's connect() to connect to micro:bit data loggers.
4. 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"

Loading

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

Loading

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

Loading

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

Loading

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

Loading

Security access

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

Loading

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