From 63a1026dae9695781ce3cfae2b3c03ab4dc2fb49 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Wed, 19 Apr 2023 11:52:58 -0500 Subject: [PATCH] ble-pybricks-service: document @since --- src/ble-pybricks-service/actions.ts | 10 +++ src/ble-pybricks-service/protocol.ts | 116 +++++++++++++++++++++++---- 2 files changed, 110 insertions(+), 16 deletions(-) diff --git a/src/ble-pybricks-service/actions.ts b/src/ble-pybricks-service/actions.ts index a2e70d47..282823f7 100644 --- a/src/ble-pybricks-service/actions.ts +++ b/src/ble-pybricks-service/actions.ts @@ -47,6 +47,8 @@ export const didNotifyEvent = createAction((value: DataView) => ({ /** * Action that requests a stop user program to be sent. * @param id Unique identifier for this transaction. + * + * @since Pybricks Profile v1.0.0 */ export const sendStopUserProgramCommand = createAction((id: number) => ({ type: 'blePybricksServiceCommand.action.sendStopUserProgram', @@ -56,6 +58,8 @@ export const sendStopUserProgramCommand = createAction((id: number) => ({ /** * Action that requests a start user program to be sent. * @param id Unique identifier for this transaction. + * + * @since Pybricks Profile v1.2.0 */ export const sendStartUserProgramCommand = createAction((id: number) => ({ type: 'blePybricksServiceCommand.action.sendStartUserProgram', @@ -65,6 +69,8 @@ export const sendStartUserProgramCommand = createAction((id: number) => ({ /** * Action that requests a start interactive REPL to be sent. * @param id Unique identifier for this transaction. + * + * @since Pybricks Profile v1.2.0 */ export const sendStartReplCommand = createAction((id: number) => ({ type: 'blePybricksServiceCommand.action.sendStartRepl', @@ -75,6 +81,8 @@ export const sendStartReplCommand = createAction((id: number) => ({ * Action that requests to write user program metadata. * @param id Unique identifier for this transaction. * @param size The size of the user program in bytes. + * + * @since Pybricks Profile v1.2.0 */ export const sendWriteUserProgramMetaCommand = createAction( (id: number, size: number) => ({ @@ -89,6 +97,8 @@ export const sendWriteUserProgramMetaCommand = createAction( * @param id Unique identifier for this transaction. * @param offset The offset in bytes from the user RAM base address. * @param payload The bytes to write. + * + * @since Pybricks Profile v1.2.0 */ export const sendWriteUserRamCommand = createAction( (id: number, offset: number, payload: ArrayBuffer) => ({ diff --git a/src/ble-pybricks-service/protocol.ts b/src/ble-pybricks-service/protocol.ts index 893ac75f..74309b6a 100644 --- a/src/ble-pybricks-service/protocol.ts +++ b/src/ble-pybricks-service/protocol.ts @@ -16,22 +16,48 @@ export const pybricksHubCapabilitiesCharacteristicUUID = /** Commands are instructions sent to the hub. */ export enum CommandType { - /** Request to stop the user program, if it is running. */ + /** + * Request to stop the user program, if it is running. + * + * @since Pybricks Profile v1.0.0 + */ StopUserProgram = 0, - /** Request to start the user program. */ + /** + * Request to start the user program. + * + * @since Pybricks Profile v1.2.0 + */ StartUserProgram = 1, - /** Request to start the interactive REPL. */ + /** + * Request to start the interactive REPL. + * + * @since Pybricks Profile v1.2.0 + */ StartRepl = 2, - /** Request to write user program metadata. */ + /** + * Request to write user program metadata. + * + * @since Pybricks Profile v1.2.0 + */ WriteUserProgramMeta = 3, - /** Request to write to user RAM. */ + /** + * Request to write to user RAM. + * + * @since Pybricks Profile v1.2.0 + */ WriteUserRam = 4, - /** Request to reboot in firmware update mode. */ + /** + * Request to reboot in firmware update mode. + * + * @since Pybricks Profile v1.2.0 + */ ResetInUpdateMode = 5, } /** * Creates a {@link CommandType.StopUserProgram} message. + * + * @since Pybricks Profile v1.0.0 */ export function createStopUserProgramCommand(): Uint8Array { const msg = new Uint8Array(1); @@ -41,6 +67,8 @@ export function createStopUserProgramCommand(): Uint8Array { /** * Creates a {@link CommandType.StartUserProgram} message. + * + * @since Pybricks Profile v1.2.0 */ export function createStartUserProgramCommand(): Uint8Array { const msg = new Uint8Array(1); @@ -50,6 +78,8 @@ export function createStartUserProgramCommand(): Uint8Array { /** * Creates a {@link CommandType.StartRepl} message. + * + * @since Pybricks Profile v1.2.0 */ export function createStartReplCommand(): Uint8Array { const msg = new Uint8Array(1); @@ -60,6 +90,8 @@ export function createStartReplCommand(): Uint8Array { /** * Creates a {@link CommandType.WriteUserProgramMeta} message. * @param size The size of the user program in bytes. + * + * @since Pybricks Profile v1.2.0 */ export function createWriteUserProgramMetaCommand(size: number): Uint8Array { const msg = new Uint8Array(5); @@ -73,6 +105,8 @@ export function createWriteUserProgramMetaCommand(size: number): Uint8Array { * Creates a {@link CommandType.WriteUserRam} message. * @param offset The offset from the user RAM base address. * @param payload The bytes to write. + * + * @since Pybricks Profile v1.2.0 */ export function createWriteUserRamCommand( offset: number, @@ -88,26 +122,66 @@ export function createWriteUserRamCommand( /** Events are notifications received from the hub. */ export enum EventType { - /** Status report. Received when notifications are enabled and when status changes. */ + /** + * Status report event. + * + * Received when notifications are enabled and when status changes. + * + * @since Pybricks Profile v1.0.0 + */ StatusReport = 0, } /** Status indications received by Event.StatusReport */ export enum Status { - /** Battery voltage is low. */ + /** + * Battery voltage is low. + * + * @since Pybricks Profile v1.0.0 + */ BatteryLowVoltageWarning = 0, - /** Battery voltage is critically low. */ + /** + * Battery voltage is critically low. + * + * @since Pybricks Profile v1.0.0 + */ BatteryLowVoltageShutdown = 1, - /** Battery current is too high. */ + /** + * Battery current is too high. + * + * @since Pybricks Profile v1.0.0 + */ BatteryHighCurrent = 2, - /** Bluetooth Low Energy is advertising/discoverable. */ + /** + * Bluetooth Low Energy is advertising/discoverable. + * + * @since Pybricks Profile v1.0.0 + */ BLEAdvertising = 3, - /** Bluetooth Low Energy has low signal. */ + /** + * Bluetooth Low Energy has low signal. + * + * @since Pybricks Profile v1.0.0 + */ BLELowSignal = 4, - /** Power button is currently pressed. */ + /** + * Power button is currently pressed. + * + * @since Pybricks Profile v1.0.0 + */ PowerButtonPressed = 5, - /** User program is currently running. */ + /** + * User program is currently running. + * + * @since Pybricks Profile v1.0.0 + */ UserProgramRunning = 6, + /** + * Hub is shutting down. + * + * @since Pybricks Profile v1.1.0 + */ + Shutdown = 7, } /** Converts a Status enum value to a bit flag. */ @@ -124,6 +198,8 @@ export function getEventType(msg: DataView): EventType { * Parses the payload of a status report message. * @param msg The raw message data. * @returns The status as bit flags. + * + * @since Pybricks Profile v1.0.0 */ export function parseStatusReport(msg: DataView): number { assert(msg.getUint8(0) === EventType.StatusReport, 'expecting status report event'); @@ -148,9 +224,17 @@ export class ProtocolError extends Error { * Hub capability flags for the hub capabilities characteristic. */ export enum HubCapabilityFlag { - /** Hub has an interactive REPL. */ + /** + * Hub has an interactive REPL. + * + * @since Pybricks Profile v1.2.0 + */ HasRepl = 1 << 0, - /** Hub supports {@link FileFormat.MultiMpy6} */ + /** + * Hub supports {@link FileFormat.MultiMpy6} + * + * @since Pybricks Profile v1.2.0 + */ UserProgramMultiMpy6 = 1 << 1, }