ultimatedarktower 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Chris Zeller (Koerner)
+
+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.

package/README.md

@@ -0,0 +1,138 @@
+# UltimateDarkTower
+
+A JavaScript/TypeScript library for controlling the Bluetooth-enabled tower from Restoration Games' Return to Dark Tower board game. Control lights, sounds, drum rotation, and track game state through Web Bluetooth.
+
+I have spent many hours reverse engineering the Tower's protocol in order to create this library, I look forward to what others will create using this! - Chris
+
+## Table of Contents
+
+- [UltimateDarkTower](#ultimatedarktower)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Live Examples](#live-examples)
+  - [Installation](#installation)
+  - [Documentation](#documentation)
+    - [📖 Complete API Reference](#-complete-api-reference)
+    - [Key Topics Covered:](#key-topics-covered)
+  - [Development](#development)
+    - [Building and Testing](#building-and-testing)
+    - [Project Structure](#project-structure)
+  - [Browser Support](#browser-support)
+  - [Known Issues](#known-issues)
+  - [Community](#community)
+
+## Features
+
+-   **Bluetooth Connection Management** - Reliable connection with automatic monitoring and disconnect detection
+-   **Tower Control** - Complete control over lights, sounds, and drum rotation
+-   **Game State Tracking** - Track glyph positions, broken seals, and skull counts
+-   **Event System** - Callback-based event handling for tower events
+-   **TypeScript Support** - Full TypeScript definitions and type safety
+-   **Comprehensive Logging** - Multi-output logging system for debugging
+-   **Battery Monitoring** - Real-time battery level tracking and low battery warnings
+
+## Live Examples
+
+Try the library in action! Just power on your Tower and visit:
+
+-   **[Tower Controller](https://chessmess.github.io/UltimateDarkTower/dist/examples/controller/TowerController.html)** - Replicates official app functionality and gives examples of library functionality.
+
+-   **[Tower Game](https://chessmess.github.io/UltimateDarkTower/dist/examples/game/TowerGame.html)** - "The Tower's Challenge" - a complete game using just the tower
+
+_Requires Web Bluetooth support (Chrome, Edge, Samsung Internet). For iOS, use the [Bluefy app](https://apps.apple.com/us/app/bluefy-web-ble-browser/id1492822055)._
+
+## Installation
+
+```bash
+npm install ultimatedarktower
+```
+
+## Documentation
+
+### 📖 [Complete API Reference](Reference.md)
+
+Comprehensive documentation with TypeScript examples, best practices, and troubleshooting guides.
+
+### Key Topics Covered:
+
+-   **Connection Management** - Connecting, disconnecting, and monitoring connection health
+-   **Tower Control** - Detailed coverage of all tower commands (lights, sounds, rotation)
+-   **Glyph System** - Automatic tracking of glyph positions as towers rotate
+-   **Seal Management** - Breaking seals and tracking game state
+-   **Event Handling** - Callback system for tower events
+-   **Logging System** - Multi-output logging for debugging and monitoring
+-   **Best Practices** - Performance tips, error handling, and common patterns
+-   **Troubleshooting** - Solutions for common issues and debugging techniques
+
+## Development
+
+### Building and Testing
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Watch mode for development
+npm run watch
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts                  # Main exports
+├── UltimateDarkTower.ts      # Main class
+├── udtBleConnection.ts       # Bluetooth connection management
+├── udtTowerCommands.ts       # Tower command implementations
+├── udtCommandFactory.ts      # Command creation utilities
+├── udtCommandQueue.ts        # Command queue management
+├── udtTowerResponse.ts       # Response handling
+├── udtTowerState.ts          # Tower state management
+├── udtHelpers.ts             # Utility helper functions
+├── udtLogger.ts              # Logging system
+└── udtConstants.ts           # Constants and type definitions
+
+examples/
+├── controller/               # Tower controller web app
+├── game/                     # Tower game web app
+└── assets/                   # Shared assets (images, fonts, etc.)
+```
+
+## Browser Support
+
+Web Bluetooth is required for this library to function.
+
+**✅ Supported Browsers:**
+
+-   Chrome (desktop and Android)
+-   Microsoft Edge
+-   Samsung Internet
+
+**📱 iOS Support:** Use the [Bluefy app](https://apps.apple.com/us/app/bluefy-web-ble-browser/id1492822055) when on iPhone or iPads as Chrome/Safari does not have Web Bluetooth support on Apples platform at the moment.
+
+**❌ Not Supported:** Firefox, Safari ([compatibility details](https://caniuse.com/?search=web%20bluetooth))
+
+## Known Issues
+
+This library is in **Release Candidate** status. Current limitations:
+
+-   **Tower Response Handling** - Not all tower responses are fully processed
+    common game patterns are planned
+
+> See [Reference.md](Reference.md) for performance best practices and workarounds.
+
+## Community
+
+Questions? Ideas? Join us on our [Discord Server](https://discord.com/channels/722465956265197618/1167555008376610945/1167842435766952158)!

package/dist/src/UltimateDarkTower.d.ts

@@ -0,0 +1,379 @@
+import { type Lights, type TowerSide, type SealIdentifier, type Glyphs } from './udtConstants';
+import { type TowerState } from './udtTowerState';
+import { type LogOutput } from './udtLogger';
+import { type ConnectionStatus } from './udtBleConnection';
+/**
+ * Configuration interface for controlling which tower responses should be logged
+ */
+interface TowerResponseConfig {
+    TOWER_STATE: boolean;
+    INVALID_STATE: boolean;
+    HARDWARE_FAILURE: boolean;
+    MECH_JIGGLE_TRIGGERED: boolean;
+    MECH_UNEXPECTED_TRIGGER: boolean;
+    MECH_DURATION: boolean;
+    DIFFERENTIAL_READINGS: boolean;
+    BATTERY_READING: boolean;
+    CALIBRATION_FINISHED: boolean;
+    LOG_ALL: boolean;
+}
+/**
+ * @title UltimateDarkTower
+ * @description
+ * The UltimateDarkTower class is the main control interface for the Return To Dark Tower board game device.
+ * It provides a comprehensive API for interacting with the tower through Bluetooth Low Energy (BLE).
+ *
+ * Usage:
+ * 1. Create instance: const tower = new UltimateDarkTower()
+ * 2. Connect to tower: await tower.connect()
+ * 3. Calibrate tower: await tower.calibrate()
+ * 4. Use tower commands: await tower.playSound(1), await tower.Lights({...}), etc.
+ * 5. Clean up: await tower.cleanup()
+ *
+ * Event Callbacks:
+ * - onTowerConnect: Called when tower connects
+ * - onTowerDisconnect: Called when tower disconnects
+ * - onCalibrationComplete: Called when calibration finishes
+ * - onSkullDrop: Called when skulls are dropped into the tower
+ * - onBatteryLevelNotify: Called when battery level updates
+ * - onTowerStateUpdate: Called whenever the tower state is updated
+ */
+declare class UltimateDarkTower {
+    private logger;
+    private bleConnection;
+    private towerEventCallbacks;
+    private responseProcessor;
+    private commandFactory;
+    private towerCommands;
+    private retrySendCommandCountRef;
+    retrySendCommandMax: number;
+    currentBatteryValue: number;
+    previousBatteryValue: number;
+    currentBatteryPercentage: number;
+    previousBatteryPercentage: number;
+    private brokenSeals;
+    private currentTowerState;
+    private glyphPositions;
+    onTowerConnect: () => void;
+    onTowerDisconnect: () => void;
+    onCalibrationComplete: () => void;
+    onSkullDrop: (towerSkullCount: number) => void;
+    onBatteryLevelNotify: (millivolts: number) => void;
+    onTowerStateUpdate: (newState: TowerState, oldState: TowerState, source: string) => void;
+    constructor();
+    /**
+     * Initialize the logger with default console output
+     */
+    private initializeLogger;
+    /**
+     * Initialize all tower components and their dependencies
+     */
+    private initializeComponents;
+    /**
+     * Set up the tower response callback after all components are initialized
+     */
+    private setupTowerResponseCallback; /**
+     * Create tower event callbacks for BLE connection
+     */
+    private createTowerEventCallbacks;
+    /**
+     * Create command dependencies object for tower commands
+     */
+    private createCommandDependencies;
+    /**
+     * Update battery state values
+     */
+    private updateBatteryState;
+    private _logDetail;
+    get logDetail(): boolean;
+    set logDetail(value: boolean);
+    /**
+     * Update tower command dependencies when configuration changes
+     */
+    private updateTowerCommandDependencies;
+    get isConnected(): boolean;
+    get isCalibrated(): boolean;
+    get performingCalibration(): boolean;
+    get performingLongCommand(): boolean;
+    get towerSkullDropCount(): number;
+    get txCharacteristic(): any;
+    get currentBattery(): number;
+    get previousBattery(): number;
+    get currentBatteryPercent(): number;
+    get previousBatteryPercent(): number;
+    get batteryNotifyFrequency(): number;
+    set batteryNotifyFrequency(value: number);
+    get batteryNotifyOnValueChangeOnly(): boolean;
+    set batteryNotifyOnValueChangeOnly(value: boolean);
+    get batteryNotifyEnabled(): boolean;
+    set batteryNotifyEnabled(value: boolean);
+    get logTowerResponses(): boolean;
+    set logTowerResponses(value: boolean);
+    get logTowerResponseConfig(): TowerResponseConfig;
+    set logTowerResponseConfig(value: TowerResponseConfig);
+    /**
+     * Initiates tower calibration to determine the current position of all tower drums.
+     * This must be performed after connection before other tower operations.
+     * @returns Promise that resolves when calibration command is sent
+     */
+    calibrate(): Promise<void>;
+    /**
+     * Plays a sound from the tower's audio library.
+     * @param soundIndex - Index of the sound to play (1-based, must be valid in TOWER_AUDIO_LIBRARY)
+     * @returns Promise that resolves when sound command is sent
+     */
+    playSound(soundIndex: number): Promise<void>;
+    /**
+     * Controls the tower's LED lights including doorway, ledge, and base lights.
+     * @param lights - Light configuration object specifying which lights to control and their effects
+     * @returns Promise that resolves when light command is sent
+     */
+    lights(lights: Lights): Promise<void>;
+    /**
+     * Controls the tower's LED lights including doorway, ledge, and base lights.
+     * @deprecated Use `lights()` instead. This method will be removed in a future version.
+     * @param lights - Light configuration object specifying which lights to control and their effects
+     * @returns Promise that resolves when light command is sent
+     */
+    Lights(lights: Lights): Promise<void>;
+    /**
+     * Sends a raw command packet directly to the tower (for testing purposes).
+     * @param command - The raw command packet to send
+     * @returns Promise that resolves when command is sent
+     */
+    sendTowerCommandDirect(command: Uint8Array): Promise<void>;
+    /**
+     * Sends a light override command to control specific light patterns.
+     * @param light - Light override value to send
+     * @param soundIndex - Optional sound to play with the light override
+     * @returns Promise that resolves when light override command is sent
+     */
+    lightOverrides(light: number, soundIndex?: number): Promise<void>;
+    /**
+     * Rotates tower drums to specified positions.
+     * @param top - Position for the top drum ('north', 'east', 'south', 'west')
+     * @param middle - Position for the middle drum
+     * @param bottom - Position for the bottom drum
+     * @param soundIndex - Optional sound to play during rotation
+     * @returns Promise that resolves when rotate command is sent
+     */
+    Rotate(top: TowerSide, middle: TowerSide, bottom: TowerSide, soundIndex?: number): Promise<void>;
+    /**
+     * Resets the tower's internal skull drop counter to zero.
+     * @returns Promise that resolves when reset command is sent
+     */
+    resetTowerSkullCount(): Promise<void>;
+    /**
+     * Sets a specific LED using stateful commands that preserve all other tower state.
+     * This is the recommended way to control individual LEDs.
+     * @param layerIndex - Layer index (0-5: TopRing, MiddleRing, BottomRing, Ledge, Base1, Base2)
+     * @param lightIndex - Light index within layer (0-3)
+     * @param effect - Light effect (0=off, 1=on, 2=slow pulse, 3=fast pulse, etc.)
+     * @param loop - Whether to loop the effect
+     * @returns Promise that resolves when command is sent
+     */
+    setLED(layerIndex: number, lightIndex: number, effect: number, loop?: boolean): Promise<void>;
+    /**
+     * Plays a sound using stateful commands that preserve existing tower state.
+     * @param soundIndex - Index of the sound to play (1-based)
+     * @param loop - Whether to loop the audio
+     * @param volume - Audio volume (0-15), optional
+     * @returns Promise that resolves when command is sent
+     */
+    playSoundStateful(soundIndex: number, loop?: boolean, volume?: number): Promise<void>;
+    /**
+     * Rotates a single drum using stateful commands that preserve existing tower state.
+     * @param drumIndex - Drum index (0=top, 1=middle, 2=bottom)
+     * @param position - Target position (0=north, 1=east, 2=south, 3=west)
+     * @param playSound - Whether to play sound during rotation
+     * @returns Promise that resolves when command is sent
+     */
+    rotateDrumStateful(drumIndex: number, position: number, playSound?: boolean): Promise<void>;
+    /**
+     * Rotates tower drums to specified positions using stateful commands that preserve existing tower state.
+     * This is the recommended way to rotate drums as it preserves LEDs and other tower state.
+     * @param top - Position for the top drum ('north', 'east', 'south', 'west')
+     * @param middle - Position for the middle drum
+     * @param bottom - Position for the bottom drum
+     * @param soundIndex - Optional sound to play during rotation
+     * @returns Promise that resolves when rotate command is sent
+     */
+    rotateWithState(top: TowerSide, middle: TowerSide, bottom: TowerSide, soundIndex?: number): Promise<void>;
+    /**
+     * Gets the current complete tower state if available.
+     * @returns The current tower state object
+     */
+    getCurrentTowerState(): TowerState;
+    /**
+     * Sends a complete tower state to the tower, preserving existing state.
+     * Audio state is automatically cleared to prevent sounds from persisting across commands.
+     * @param towerState - The tower state to send
+     * @returns Promise that resolves when the command is sent
+     */
+    sendTowerState(towerState: TowerState): Promise<void>;
+    /**
+     * Sets the tower state with comprehensive logging of changes.
+     * @param newState - The new tower state to set
+     * @param source - Source identifier for logging (e.g., "sendTowerState", "tower response")
+     */
+    private setTowerState;
+    /**
+     * Updates the current tower state from a tower response.
+     * Called internally when tower state responses are received.
+     * Audio state is reset to prevent sounds from persisting across commands.
+     * @param stateData - The 19-byte state data from tower response
+     */
+    private updateTowerStateFromResponse;
+    /**
+     * Breaks a single seal on the tower, playing appropriate sound and lighting effects.
+     * @param seal - Seal identifier to break (e.g., {side: 'north', level: 'middle'})
+     * @param volume - Optional volume override (0=loud, 1=medium, 2=quiet, 3=mute). Uses current tower state if not provided.
+     * @returns Promise that resolves when seal break sequence is complete
+     */
+    breakSeal(seal: SealIdentifier, volume?: number): Promise<void>;
+    /**
+     * Randomly rotates specified tower levels to random positions.
+     * @param level - Level configuration: 0=all, 1=top, 2=middle, 3=bottom, 4=top&middle, 5=top&bottom, 6=middle&bottom
+     * @returns Promise that resolves when rotation command is sent
+     */
+    randomRotateLevels(level?: number): Promise<void>;
+    /**
+     * Gets the current position of a specific drum level.
+     * @param level - The drum level to get position for
+     * @returns The current position of the specified drum level
+     */
+    getCurrentDrumPosition(level: 'top' | 'middle' | 'bottom'): TowerSide;
+    /**
+     * Sets the initial glyph positions from calibration.
+     * Called automatically when calibration completes.
+     */
+    private setGlyphPositionsFromCalibration;
+    /**
+     * Gets the current position of a specific glyph.
+     * @param glyph - The glyph to get position for
+     * @returns The current position of the glyph, or null if not calibrated
+     */
+    getGlyphPosition(glyph: Glyphs): TowerSide | null;
+    /**
+     * Gets all current glyph positions.
+     * @returns Object mapping each glyph to its current position (or null if not calibrated)
+     */
+    getAllGlyphPositions(): {
+        [key in Glyphs]: TowerSide | null;
+    };
+    /**
+     * Gets all glyphs currently facing a specific direction.
+     * @param direction - The direction to check for (north, east, south, west)
+     * @returns Array of glyph names that are currently facing the specified direction
+     */
+    getGlyphsFacingDirection(direction: TowerSide): Glyphs[];
+    /**
+     * Updates glyph positions after a drum rotation.
+     * @param level - The drum level that was rotated
+     * @param rotationSteps - Number of steps rotated (1 = 90 degrees clockwise)
+     */
+    private updateGlyphPositionsAfterRotation;
+    /**
+     * Calculates rotation steps and updates glyph positions for a specific level.
+     * @param level - The drum level that was rotated
+     * @param oldPosition - The position before rotation
+     * @param newPosition - The position after rotation
+     */
+    private calculateAndUpdateGlyphPositions;
+    /**
+     * Updates glyph positions for a specific level rotation.
+     * @param level - The drum level that was rotated
+     * @param newPosition - The new position the drum was rotated to
+     * @deprecated Use calculateAndUpdateGlyphPositions instead
+     */
+    private updateGlyphPositionsForRotation;
+    /**
+     * Checks if a specific seal is broken.
+     * @param seal - The seal identifier to check
+     * @returns True if the seal is broken, false otherwise
+     */
+    isSealBroken(seal: SealIdentifier): boolean;
+    /**
+     * Gets a list of all broken seals.
+     * @returns Array of SealIdentifier objects representing all broken seals
+     */
+    getBrokenSeals(): SealIdentifier[];
+    /**
+     * Resets the broken seals tracking (clears all broken seals).
+     */
+    resetBrokenSeals(): void;
+    /**
+     * Gets a random unbroken seal that can be passed to breakSeal().
+     * @returns A random SealIdentifier that is not currently broken, or null if all seals are broken
+     */
+    getRandomUnbrokenSeal(): SealIdentifier | null;
+    /**
+     * Establishes a Bluetooth connection to the Dark Tower device.
+     * Initializes GATT services, characteristics, and starts connection monitoring.
+     * @returns {Promise<void>} Promise that resolves when connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the tower device and cleans up resources.
+     * @returns {Promise<void>} Promise that resolves when disconnection is complete
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Configure logger outputs for this UltimateDarkTower instance
+     * @param {LogOutput[]} outputs - Array of log outputs to use (e.g., ConsoleOutput, DOMOutput)
+     */
+    setLoggerOutputs(outputs: LogOutput[]): void;
+    /**
+     * Sends a command packet to the tower via Bluetooth with error handling and retry logic.
+     * @param {Uint8Array} command - The command packet to send to the tower
+     * @returns {Promise<void>} Promise that resolves when command is sent successfully
+     */
+    sendTowerCommand(command: Uint8Array): Promise<void>;
+    /**
+     * Converts a command packet to a hex string representation for debugging.
+     * @param {Uint8Array} command - Command packet to convert
+     * @returns {string} Hex string representation of the command packet
+     */
+    commandToPacketString(command: Uint8Array): string;
+    /**
+     * Converts battery voltage in millivolts to percentage.
+     * @param {number} mv - Battery voltage in millivolts
+     * @returns {string} Battery percentage as formatted string (e.g., "75%")
+     */
+    milliVoltsToPercentage(mv: number): string;
+    /**
+     * Enable or disable connection monitoring
+     * @param {boolean} enabled - Whether to enable connection monitoring
+     */
+    setConnectionMonitoring(enabled: boolean): void;
+    /**
+     * Configure connection monitoring parameters
+     * @param {number} [frequency=2000] - How often to check connection (milliseconds)
+     * @param {number} [timeout=30000] - How long to wait for responses before considering connection lost (milliseconds)
+     */
+    configureConnectionMonitoring(frequency?: number, timeout?: number): void;
+    /**
+     * Configure battery heartbeat monitoring parameters
+     * Tower sends battery status every ~200ms, so this is the most reliable disconnect indicator
+     * @param {boolean} [enabled=true] - Whether to enable battery heartbeat monitoring
+     * @param {number} [timeout=3000] - How long to wait for battery status before considering disconnected (milliseconds)
+     * @param {boolean} [verifyConnection=true] - Whether to verify connection status before triggering disconnection on heartbeat timeout
+     */
+    configureBatteryHeartbeatMonitoring(enabled?: boolean, timeout?: number, verifyConnection?: boolean): void;
+    /**
+     * Check if the tower is currently connected
+     * @returns {Promise<boolean>} True if connected and responsive
+     */
+    isConnectedAndResponsive(): Promise<boolean>;
+    /**
+     * Get detailed connection status including heartbeat information
+     * @returns {Object} Object with connection details
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Clean up resources and disconnect properly
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     */
+    cleanup(): Promise<void>;
+}
+export default UltimateDarkTower;