Skip to content

Architecture Overview

This document provides a high-level architecture overview of the ALPHA HWR protocol implementation.

System Architecture

graph TD
    A[Application/CLI] --> B[Client Facade]
    B --> C[Services Layer]
    C --> D[Protocol Layer]
    D --> E[Transport Layer]
    E --> F[Core Layer]
    F --> G[BLE Stack]
    G --> H[Pump Hardware]

Layer Responsibilities

1. Core Layer

Purpose: Foundation for BLE communication and session management

Components: - authentication.py - Authentication handshake - session.py - Connection state machine - transport.py - BLE send/receive abstraction

Key Responsibilities: - Manage BLE connection lifecycle - Execute authentication sequence - Handle packet transmission/reception - Maintain session state

2. Protocol Layer

Purpose: GENI protocol encoding/decoding

Components: - codec.py - Primitive encoding/decoding (floats, ints) - frame_builder.py - Construct GENI frames - frame_parser.py - Parse GENI frames - telemetry_decoder.py - Decode telemetry payloads

Key Responsibilities: - Build valid GENI protocol packets - Parse received packets - Calculate CRC checksums - Extract data from payloads

3. Services Layer

Purpose: Business logic for pump operations

Components: - telemetry.py - Read measurements - control.py - Pump control operations - device_info.py - Device information - schedule.py - Schedule management - configuration.py - Backup/restore

Key Responsibilities: - Expose high-level operations - Handle complex multi-step workflows - Validate inputs - Manage service state

4. Client Facade

Purpose: Simple unified API

File: client.py

Key Responsibilities: - Single entry point for applications - Manage service lifecycles - Handle connection/disconnection - Provide context manager interface

Sequence Diagrams

Authentication Sequence

sequenceDiagram
    participant App
    participant Auth
    participant Transport
    participant Pump

    App->>Auth: authenticate()
    Auth->>Transport: send(LEGACY_MAGIC) x3
    Transport->>Pump: BLE write
    Auth->>Transport: send(CLASS10_UNLOCK) x5
    Transport->>Pump: BLE write
    Auth->>Transport: send(EXTEND_1)
    Auth->>Transport: send(EXTEND_2)
    Transport->>Pump: BLE write
    Pump-->>Transport: ACK
    Auth-->>App: Success

Telemetry Reading

sequenceDiagram
    participant App
    participant Telemetry
    participant Protocol
    participant Transport
    participant Pump

    App->>Telemetry: read_once()
    Telemetry->>Protocol: build_info_command(0x0A, 0x45, 0x57)
    Protocol->>Transport: send(packet)
    Transport->>Pump: BLE write
    Pump-->>Transport: Response
    Transport-->>Protocol: raw_data
    Protocol->>Protocol: parse_frame(raw_data)
    Protocol->>Protocol: decode_telemetry(frame)
    Protocol-->>Telemetry: TelemetryData
    Telemetry-->>App: TelemetryData

Control Mode Setting

sequenceDiagram
    participant App
    participant Control
    participant Protocol
    participant Transport
    participant Pump

    App->>Control: set_mode("constant_pressure", 1.5)
    Control->>Control: validate_setpoint(1.5)
    Control->>Protocol: encode_float_be(14710.0)
    Protocol->>Protocol: build_set_command(0x5600, 0x0601, data)
    Protocol->>Transport: send(packet)
    Transport->>Pump: BLE write
    Pump-->>Transport: ACK
    Transport-->>Control: Success
    Control-->>App: True

Data Flow

Request Flow

graph TD
    App[Application] --> Client[Client Facade]
    Client --> Services[Service Layer]
    Services --> Protocol[Protocol Layer]
    Protocol --> Transport[Transport Layer]
    Transport --> Pump[Pump Hardware]

Response Flow

graph TD
    Pump[Pump Hardware] --> Transport[Transport Layer]
    Transport --> Protocol[Protocol Layer]
    Protocol --> Services[Service Layer]
    Services --> Client[Client Facade]
    Client --> App[Application]

State Management

Session States

stateDiagram-v2
    [*] --> DISCONNECTED
    DISCONNECTED --> CONNECTED: connect()
    CONNECTED --> AUTHENTICATING: authenticate()
    AUTHENTICATING --> AUTHENTICATED: success
    AUTHENTICATING --> ERROR: failure
    AUTHENTICATED --> CONNECTED: timeout
    CONNECTED --> DISCONNECTED: disconnect()
    ERROR --> DISCONNECTED: reset

Transport States

  • IDLE: No active operation
  • SENDING: Packet transmission in progress
  • WAITING: Awaiting response
  • RECEIVING: Processing notification
  • ERROR: Communication failure

Key Design Patterns

1. Layered Architecture

Each layer has clear boundaries and responsibilities. Upper layers depend only on adjacent lower layers.

2. Async/Await

All I/O operations are asynchronous to prevent blocking.

3. Context Managers

Resources (connections, sessions) use context managers for automatic cleanup.

4. Service Locator

Client facade provides access to all services through a single interface.

5. Strategy Pattern

Different control modes, schedule types, etc. use strategy pattern.

Error Handling

Error Propagation

graph TD
    Services[Service Layer] -- raises --> Error[AlphaHWRError]
    Error -- catches --> Client[Client Facade]
    Client -- re-raises --> App[Application]
    App -- handles --> User[User]

Error Types

  • ConnectionError: BLE connection issues
  • AuthenticationError: Authentication failure
  • ProtocolError: Invalid packet or CRC
  • TimeoutError: Operation timeout
  • ValidationError: Invalid input

Thread Safety

Concurrent Access

  • Transport: Uses asyncio locks for sequential command execution
  • Session: Thread-safe state machine
  • Services: Stateless operations (safe for concurrent use)

Lock Hierarchy

Transport Lock (lowest)
  ↓
Session Lock
  ↓
Service Lock (highest)

Always acquire locks from highest to lowest to prevent deadlocks.

Performance Considerations

Latency

  • Authentication: ~500ms
  • Single telemetry read: ~100-200ms
  • Control command: ~100-150ms

Throughput

  • BLE MTU: 20 bytes (default)
  • Max packet size: ~250 bytes
  • Notifications: Up to 1Hz from pump

Resource Usage

  • Memory: Minimal (< 1MB for client)
  • CPU: Low (BLE and parsing only)
  • Battery: Dependent on connection interval

Security

Authentication

  • Custom challenge-response using magic packets
  • No encryption at application layer
  • Relies on BLE pairing for security

Data Privacy

  • Telemetry data sent in clear text over BLE
  • Recommend BLE pairing for sensitive deployments

Extensibility

Adding New Services

  1. Create service class in services/
  2. Add to client.py facade
  3. Document in guides
  4. Add tests

Adding New Commands

  1. Define in protocol/frame_builder.py
  2. Parse in protocol/frame_parser.py
  3. Expose in relevant service
  4. Add test vectors

Supporting New Pumps

  1. Verify GENI protocol compatibility
  2. Update constants if needed
  3. Add pump-specific tests
  4. Document differences

Testing Strategy

Unit Tests

  • Each layer tested independently
  • Mock dependencies
  • Test vectors for validation

Integration Tests

  • End-to-end with mock pump
  • Real hardware tests
  • Cross-platform validation

Reference Tests

  • Portable test suite
  • Byte-level validation
  • Other languages can use same tests

Deployment

Packaging

  • Python: PyPI package
  • JavaScript: npm package
  • Rust: crates.io
  • Others: Language-specific registries

Dependencies

  • BLE library (Bleak, noble, btleplug, etc.)
  • Async runtime (asyncio, tokio, etc.)
  • Optional: CLI framework, GUI toolkit

Next Steps

  1. Review Layer-by-Layer Guide for implementation details
  2. Use Checklist to track progress
  3. Validate with Test Vectors
  4. Check Common Pitfalls for known issues