node-poweredup 9.0.0 → 10.0.0

package/dist/node/protocol.d.ts

@@ -0,0 +1,340 @@
+/**
+ * PoweredUp Protocol
+ * LEGO Wireless Protocol 3.0 (LWP3) message encoding/decoding
+ * https://lego.github.io/lego-ble-wireless-protocol-docs/
+ */
+import { DeviceType, PortEvent, AlertType, BrakingStyle, Profile, Color, MotorFeedback } from "./types";
+export declare const BLE_SERVICE_UUID = "00001623-1212-efde-1623-785feabcd123";
+export declare const BLE_CHARACTERISTIC_UUID = "00001624-1212-efde-1623-785feabcd123";
+export declare const BLE_BOOTLOADER_SERVICE_UUID = "00001625-1212-efde-1623-785feabcd123";
+export declare const BLE_BOOTLOADER_CHARACTERISTIC_UUID = "00001626-1212-efde-1623-785feabcd123";
+export declare enum MessageType {
+    HUB_PROPERTIES = 1,
+    HUB_ACTIONS = 2,
+    HUB_ALERTS = 3,
+    HUB_ATTACHED_IO = 4,
+    GENERIC_ERROR_MESSAGES = 5,
+    HW_NETWORK_COMMANDS = 8,
+    FW_UPDATE_GO_INTO_BOOT_MODE = 16,
+    FW_UPDATE_LOCK_MEMORY = 17,
+    FW_UPDATE_LOCK_STATUS_REQUEST = 18,
+    FW_LOCK_STATUS = 19,
+    PORT_INFORMATION_REQUEST = 33,
+    PORT_MODE_INFORMATION_REQUEST = 34,
+    PORT_INPUT_FORMAT_SETUP_SINGLE = 65,
+    PORT_INPUT_FORMAT_SETUP_COMBINEDMODE = 66,
+    PORT_INFORMATION = 67,
+    PORT_MODE_INFORMATION = 68,
+    PORT_VALUE_SINGLE = 69,
+    PORT_VALUE_COMBINEDMODE = 70,
+    PORT_INPUT_FORMAT_SINGLE = 71,
+    PORT_INPUT_FORMAT_COMBINEDMODE = 72,
+    VIRTUAL_PORT_SETUP = 97,
+    PORT_OUTPUT_COMMAND = 129,
+    PORT_OUTPUT_COMMAND_FEEDBACK = 130
+}
+export declare enum HubProperty {
+    ADVERTISING_NAME = 1,
+    BUTTON = 2,
+    FW_VERSION = 3,
+    HW_VERSION = 4,
+    RSSI = 5,
+    BATTERY_VOLTAGE = 6,
+    BATTERY_TYPE = 7,
+    MANUFACTURER_NAME = 8,
+    RADIO_FIRMWARE_VERSION = 9,
+    LWP_PROTOCOL_VERSION = 10,
+    SYSTEM_TYPE_ID = 11,
+    HW_NETWORK_ID = 12,
+    PRIMARY_MAC_ADDRESS = 13,
+    SECONDARY_MAC_ADDRESS = 14,
+    HW_NETWORK_FAMILY = 15
+}
+export declare enum HubPropertyOperation {
+    SET = 1,
+    ENABLE_UPDATES = 2,
+    DISABLE_UPDATES = 3,
+    RESET = 4,
+    REQUEST_UPDATE = 5,
+    UPDATE = 6
+}
+export declare enum HubAction {
+    SWITCH_OFF_HUB = 1,
+    DISCONNECT = 2,
+    VCC_PORT_CONTROL_ON = 3,
+    VCC_PORT_CONTROL_OFF = 4,
+    ACTIVATE_BUSY_INDICATION = 5,
+    RESET_BUSY_INDICATION = 6,
+    SHUTDOWN = 47,
+    HUB_WILL_SWITCH_OFF = 48,
+    HUB_WILL_DISCONNECT = 49,
+    HUB_WILL_GO_INTO_BOOT_MODE = 50
+}
+export declare enum AlertOperation {
+    ENABLE_UPDATE = 1,
+    DISABLE_UPDATE = 2,
+    REQUEST_UPDATE = 3,
+    UPDATE = 4
+}
+export declare enum MotorSubCommand {
+    START_POWER = 1,
+    START_POWER_DUAL = 2,
+    SET_ACC_TIME = 5,
+    SET_DEC_TIME = 6,
+    START_SPEED = 7,
+    START_SPEED_DUAL = 8,
+    START_SPEED_FOR_TIME = 9,
+    START_SPEED_FOR_TIME_DUAL = 10,
+    START_SPEED_FOR_DEGREES = 11,
+    START_SPEED_FOR_DEGREES_DUAL = 12,
+    GOTO_ABSOLUTE_POSITION = 13,
+    GOTO_ABSOLUTE_POSITION_DUAL = 14,
+    PRESET_ENCODER = 19,
+    PRESET_ENCODER_DUAL = 20,
+    WRITE_DIRECT = 80,
+    WRITE_DIRECT_MODE_DATA = 81
+}
+export declare enum PortInformationType {
+    PORT_VALUE = 0,
+    MODE_INFO = 1,
+    POSSIBLE_MODE_COMBINATIONS = 2
+}
+export declare enum ModeInformationType {
+    NAME = 0,
+    RAW = 1,
+    PCT = 2,
+    SI = 3,
+    SYMBOL = 4,
+    MAPPING = 5,
+    MOTOR_BIAS = 7,
+    CAPABILITY_BITS = 8,
+    VALUE_FORMAT = 128
+}
+export declare enum ErrorCode {
+    ACK = 1,
+    MACK = 2,
+    BUFFER_OVERFLOW = 3,
+    TIMEOUT = 4,
+    COMMAND_NOT_RECOGNIZED = 5,
+    INVALID_USE = 6,
+    OVERCURRENT = 7,
+    INTERNAL_ERROR = 8
+}
+export interface HubPropertyMessage {
+    type: MessageType.HUB_PROPERTIES;
+    property: HubProperty;
+    operation: HubPropertyOperation;
+    payload: Buffer;
+}
+export interface HubActionMessage {
+    type: MessageType.HUB_ACTIONS;
+    action: HubAction;
+}
+export interface HubAlertMessage {
+    type: MessageType.HUB_ALERTS;
+    alertType: AlertType;
+    operation: AlertOperation;
+    payload: number;
+}
+export interface AttachedIOMessage {
+    type: MessageType.HUB_ATTACHED_IO;
+    portId: number;
+    event: PortEvent;
+    deviceType: DeviceType;
+    hardwareRevision?: string;
+    softwareRevision?: string;
+    portIdA?: number;
+    portIdB?: number;
+}
+export interface GenericErrorMessage {
+    type: MessageType.GENERIC_ERROR_MESSAGES;
+    commandType: number;
+    errorCode: ErrorCode;
+}
+export interface PortInformationMessage {
+    type: MessageType.PORT_INFORMATION;
+    portId: number;
+    informationType: PortInformationType;
+    capabilities?: number;
+    modeCount?: number;
+    inputModes?: number;
+    outputModes?: number;
+    modeCombinations?: number[];
+}
+export interface PortModeInformationMessage {
+    type: MessageType.PORT_MODE_INFORMATION;
+    portId: number;
+    mode: number;
+    informationType: ModeInformationType;
+    name?: string;
+    rawRange?: {
+        min: number;
+        max: number;
+    };
+    pctRange?: {
+        min: number;
+        max: number;
+    };
+    siRange?: {
+        min: number;
+        max: number;
+    };
+    symbol?: string;
+    mapping?: number;
+    motorBias?: number;
+    capabilityBits?: Buffer;
+    valueFormat?: {
+        datasetCount: number;
+        datasetType: number;
+        figures: number;
+        decimals: number;
+    };
+}
+export interface PortValueSingleMessage {
+    type: MessageType.PORT_VALUE_SINGLE;
+    portId: number;
+    value: Buffer;
+}
+export interface PortValueCombinedMessage {
+    type: MessageType.PORT_VALUE_COMBINEDMODE;
+    portId: number;
+    modeDatasets: number;
+    values: Buffer;
+}
+export interface PortInputFormatSingleMessage {
+    type: MessageType.PORT_INPUT_FORMAT_SINGLE;
+    portId: number;
+    mode: number;
+    deltaInterval: number;
+    notificationEnabled: boolean;
+}
+export interface PortInputFormatCombinedMessage {
+    type: MessageType.PORT_INPUT_FORMAT_COMBINEDMODE;
+    portId: number;
+    combinedControl: number;
+    modeDatasetPointer: number;
+}
+export interface PortOutputFeedbackMessage {
+    type: MessageType.PORT_OUTPUT_COMMAND_FEEDBACK;
+    portId: number;
+    feedback: number;
+}
+export type DecodedMessage = HubPropertyMessage | HubActionMessage | HubAlertMessage | AttachedIOMessage | GenericErrorMessage | PortInformationMessage | PortModeInformationMessage | PortValueSingleMessage | PortValueCombinedMessage | PortInputFormatSingleMessage | PortInputFormatCombinedMessage | PortOutputFeedbackMessage;
+/**
+ * Decode the message length from raw bytes
+ * Messages longer than 127 bytes use two-byte length encoding
+ */
+export declare function decodeMessageLength(data: Buffer): {
+    length: number;
+    headerSize: number;
+};
+/**
+ * Encode message length as header bytes
+ */
+export declare function encodeMessageLength(length: number): Buffer;
+/**
+ * Decode a version number from 4 bytes (BCD encoded)
+ */
+export declare function decodeVersion(data: Buffer, offset?: number): string;
+/**
+ * Decode a MAC address from 6 bytes
+ */
+export declare function decodeMACAddress(data: Buffer, offset?: number): string;
+/**
+ * Decode a complete LWP3 message
+ */
+export declare function decodeMessage(data: Buffer): DecodedMessage | null;
+/**
+ * Wrap payload with LWP3 message header
+ */
+export declare function encodeMessage(messageType: MessageType, payload: Buffer): Buffer;
+/**
+ * Create hub property request message
+ */
+export declare function createHubPropertyRequest(property: HubProperty, operation: HubPropertyOperation): Buffer;
+/**
+ * Create hub property set message (for writable properties)
+ */
+export declare function createHubPropertySet(property: HubProperty, value: Buffer): Buffer;
+/**
+ * Create hub action message
+ */
+export declare function createHubAction(action: HubAction): Buffer;
+/**
+ * Create alert subscription message
+ */
+export declare function createAlertSubscription(alertType: AlertType, enable: boolean): Buffer;
+/**
+ * Create port information request message
+ */
+export declare function createPortInformationRequest(portId: number, informationType: PortInformationType): Buffer;
+/**
+ * Create port mode information request message
+ */
+export declare function createPortModeInformationRequest(portId: number, mode: number, infoType: ModeInformationType): Buffer;
+/**
+ * Create port input format setup (subscribe/unsubscribe to notifications)
+ */
+export declare function createPortInputFormatSetup(portId: number, mode: number, deltaInterval: number, notificationEnabled: boolean): Buffer;
+/**
+ * Create virtual port setup message (connect/disconnect)
+ */
+export declare function createVirtualPortSetup(connect: boolean, portIdA: number, portIdB?: number, virtualPortId?: number): Buffer;
+/**
+ * Set motor power (unregulated)
+ */
+export declare function createStartPower(portId: number, power: number): Buffer;
+/**
+ * Set motor power for dual motors (virtual port)
+ */
+export declare function createStartPowerDual(portId: number, power1: number, power2: number): Buffer;
+/**
+ * Set motor speed (regulated)
+ */
+export declare function createStartSpeed(portId: number, speed: number, maxPower?: number, useProfile?: Profile): Buffer;
+/**
+ * Set motor speed for dual motors (virtual port)
+ */
+export declare function createStartSpeedDual(portId: number, speed1: number, speed2: number, maxPower?: number, useProfile?: Profile): Buffer;
+/**
+ * Run motor for a specified time
+ */
+export declare function createStartSpeedForTime(portId: number, time: number, speed: number, maxPower?: number, endState?: BrakingStyle, useProfile?: Profile): Buffer;
+/**
+ * Run motor for a specified number of degrees
+ */
+export declare function createStartSpeedForDegrees(portId: number, degrees: number, speed: number, maxPower?: number, endState?: BrakingStyle, useProfile?: Profile): Buffer;
+/**
+ * Go to absolute position
+ */
+export declare function createGotoAbsolutePosition(portId: number, position: number, speed: number, maxPower?: number, endState?: BrakingStyle, useProfile?: Profile): Buffer;
+/**
+ * Preset (reset) encoder position
+ */
+export declare function createPresetEncoder(portId: number, position?: number): Buffer;
+/**
+ * Set acceleration time
+ */
+export declare function createSetAccTime(portId: number, time: number, profileNumber?: number): Buffer;
+/**
+ * Set deceleration time
+ */
+export declare function createSetDecTime(portId: number, time: number, profileNumber?: number): Buffer;
+/**
+ * Set LED color by color number
+ */
+export declare function createSetLEDColor(portId: number, color: Color): Buffer;
+/**
+ * Set LED color by RGB values
+ */
+export declare function createSetLEDRGB(portId: number, red: number, green: number, blue: number): Buffer;
+/**
+ * Parse motor feedback flags
+ */
+export declare function parseMotorFeedback(feedback: number): MotorFeedback & {
+    portId: number;
+};
+/**
+ * Convert hub property payload to typed value
+ */
+export declare function parseHubPropertyValue(property: HubProperty, payload: Buffer): unknown;