CueB Gen 2 - version 8 onwards

This is the code for the CueB Gen 2. It is a different architecture to Gen 1, and is based on networked outstations which are W5500 EVB Raspberry Pi Pico boards from Wiznet.

The code is split into three parts:

• device - the code that runs on the Pico outstation, in Micropython
• server - an electron app, which serves a web interface and communicates with the outstations
• client - a React web interface, which is served by the server

Communication with Outstations

Communication between the server and the outstations is over OSC. Only one server can exist within a given subnet, as the outstations rely on keeping track of what they think the server's state is.

Outstation States

Each individual outstation is responsible for managing its own state, and the server communicates with each outstations to confirm its state.

There are two ways of changing the state of a outstation. Outstations always boot with a state of 1.

State Number	State Name	Red Button LED 🔴	Green Button LED 🟢	Remarks
0	Error			Outstation boots in this state
1	Ready			Outstation is idle
2	Unacknowledged Standby	⚡		DSM is waiting for acknowledgement of standby
3	Acknowledged Standby	🔴		Outstation has acknowledged
4	Unacknowledged Go		⚡	(not used)
5	Acknowledged Go		🟢	Will auto-reset after configured time
6	Panic/Vegas	🔴	🟢	User trying to get attention of DSM
7	Identify/Flash	⚡	⚡	To identify an outstation

Outstation changes own state

If a user presses a button on a outstation, this will change its state. The outstation will then broadcast its new state to the server, which will confirm it.

sequenceDiagram
  participant Outstation
  participant Server
  Note right of Outstation: User presses button
  Outstation->>Server: /cueb/outstationState
  Note left of Server: Two arguments: state and outstation unique ID
  loop Until acknowledged
    Outstation->>Server: /cueb/outstationState/confirmInSync
    Note left of Server: Two arguments: state and outstation unique ID
  end
  Server->>Outstation: /cueb/outstationState/confirmInSync
  Note right of Outstation: One argument: state.

Loading

Server changes outstation state

The server can send a message to change a outstation's state. The outstation will confirm that it has received the new state.

sequenceDiagram
  participant Client
  participant Server
  participant Outstation
  Client->>Server: User presses button
  Server->>Outstation: /cueb/outstationState
  Note right of Outstation: On argument: state
  Outstation->>Server: /cueb/outstationState
  Note left of Server: Two arguments: state and outstation unique ID

Loading

Ping/Pong messages

The server can send a ping message to the outstation, which will reply with a pong message. This is used to check if the outstation is still connected to the network.

sequenceDiagram
  participant Server
  participant Outstation
  Server->>Outstation: /cueb/ping
  Note right of Outstation: No arguments
  Outstation->>Server: /cueb/pong
  Note left of Server: One argument: outstation unique ID

Loading

Determining the state of a outstation

The server can, at any time, ask a outstation to transmit its state.

sequenceDiagram
  participant Server
  participant Outstation
  Server->>Outstation: /cueb/outstationState
  Note right of Outstation: No arguments
  loop Until acknowledged
    Outstation->>Server: /cueb/outstationState/confirmInSync
    Note left of Server: Two arguments: state and outstation unique ID
  end
  Server->>Outstation: /cueb/outstationState/confirmInSync
  Note right of Outstation: One argument: state.

Loading

Outstation status lights

LED State	Color	Status
On	🔴	Connected to network, and has IP
On	🟡	Received message from server in last 5 seconds
Flashing	🔴	Disconnected from network
Flashing	🟡	No messages received from server in last 10 seconds
Off	🔴	No network
Off	🟡	No messages received from server in last 10 minutes

Client / Server code

The server runs as an electron app, and serves the client code. The client code is a React app.

The server code is in the server directory, and the client code is in the client directory.

The key file in the server code is osc.ts which handles all the OSC communication with the outstations.

Package Dependencies

Server Packages

Core Framework

• electron (v28.2.3) - Desktop application framework
• electron-forge - Tool for building and publishing Electron apps
• vite - Build tool and development server

Communication

• node-osc (v9.1.0) - OSC protocol implementation
• ws (v8.16.0) - WebSocket client/server
• cors (v2.8.5) - Cross-origin resource sharing middleware
• portfinder (v1.0.32) - Port allocation utility

Database

• better-sqlite3 (v9.4.1) - SQLite3 database driver
• drizzle-orm (v0.29.3) - TypeScript ORM
• drizzle-kit - Database migration tools

API Layer

• @trpc/server (v11.0.0-next-beta) - End-to-end typesafe API
• zod (v3.22.4) - TypeScript-first schema validation

Networking

• ip (v2.0.1) - IP address utilities
• netmask (v2.0.2) - Network mask parsing

Client Packages

Core Framework

• react (v18.2.0) - UI library
• react-dom (v18.2.0) - React DOM renderer
• react-router-dom (v6.22.1) - Routing

UI Components

• @mantine/core (v7.5.3) - UI component library
• @mantine/dates - Date/time components
• @mantine/form - Form handling
• @mantine/notifications - Toast notifications
• @tabler/icons-react (v2.47.0) - Icon library

Data Management

• @tanstack/react-query (v5.21.7) - Data fetching/caching
• @trpc/client - tRPC client
• @trpc/react-query - React Query integration
• dayjs (v1.11.10) - Date manipulation

Development Tools

• typescript (v5.2.2) - TypeScript compiler
• eslint - Code linting
• postcss - CSS processing
• vite (v5.1.0) - Build tool

Updating

• Bump package.json version for client & server
• Commit to gen2 branch and push
• Create and publish a new release
• (Github action will add files to release)

Tracking deployed outstations

List of outstations produced is in the wiki: https://github.com/bstudios/CueB/wiki