Developer Guide

Contribute to TallyHub or build custom integrations

💻

GitHub Repo

🐛

Issues

💬

Discussions

Getting Started with Development

Prerequisites

• Node.js 20.9.0 or higher
• npm or yarn package manager
• Git for version control
• TypeScript knowledge recommended

Setup Development Environment

Fork and Clone

git clone https://github.com/YOUR_USERNAME/Tallyhub.git
cd Tallyhub

Install Dependencies

npm install

Start Development Server

npm run dev

Open in Browser

Navigate to http://localhost:3000

Available Scripts

npm run dev

Start development server with ts-node + nodemon (hot reload)

npm run build

Compile TypeScript to dist/ for production

npm start

Run compiled production build from dist/

npm run typecheck

TypeScript strict type checking (no emit)

npm run lint

Lint codebase (ESLint + TypeScript rules)

npm run lint:fix

Auto-fix lint issues where possible

npm run format

Format code with Prettier across the repo

npm run logs:prune

Remove log files older than 14 days

npx tallyhub

CLI launcher - builds and starts server

Project Structure

Tallyhub/
├── src/                   # TypeScript source files
│   ├── index.ts          # Main entry point
│   ├── routes/           # API routes
│   ├── services/         # Business logic
│   └── types/            # TypeScript types
├── public/               # Static assets
│   ├── firmware/         # Device firmware files
│   └── flash.html        # Firmware flasher UI
├── dist/                 # Compiled JavaScript (build output)
├── logs/                 # Application logs
├── docker/               # Docker configuration
├── firmware/             # Device firmware source
├── bin/                  # CLI tools
└── docs/                 # Documentation

Contributing Guidelines

📖 Read CONTRIBUTING.md

Before contributing, please read our comprehensive contributing guide:

View CONTRIBUTING.md on GitHub →

Branch Naming

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions or changes

Commit Message Style

Use conventional commits format:

feat: add support for TriCaster mixers
fix: resolve device discovery timeout
docs: update installation guide
refactor: improve WebSocket connection handling
chore: bump version to 1.2.0

Code Quality Gates

Before submitting a PR, ensure all quality checks pass:

npm run typecheck     # No TypeScript errors
npm run lint          # No linting errors
npm run format        # Code is formatted
npm run build         # Builds successfully

API & Integration

REST API

TallyHub provides a REST API for custom integrations:

GET/api/devices

List all registered devices

POST/api/devices

GET/api/assignments

Get camera assignments

PUT/api/assignments/:id

Update camera assignment

WebSocket API

Real-time tally updates via WebSocket:

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:3000/api/tally');

// Listen for tally updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Tally update:', data);
};

Device Discovery Protocol

Devices can discover the hub using UDP broadcast or mDNS:

• UDP Port: 7411
• mDNS Service: _tallyhub._udp.local
• TXT Records: api=3000, udp=7411, ver=1.2.0

Environment Variables

NODE_ENVdevelopment | production

Set environment mode

LOG_LEVELerror | warn | info | debug

Set logging verbosity

PORTnumber

HTTP server port (default: 3000)

GITHUB_TOKENstring

GitHub personal access token for firmware downloads

DISABLE_MDNS1 | 0

Disable mDNS service advertising

Firmware Development

TallyHub firmware is written in C++ for ESP32 devices using Arduino framework.

Firmware Directory

firmware/
├── esp32-1732s019/      # 1.9" display tally
├── m5stick-c-plus/      # M5Stick C Plus 1.1
└── m5stick-c-plus2/     # M5Stick C Plus2

Building Firmware

Use PlatformIO or Arduino IDE to build firmware:

# Using PlatformIO
cd firmware/esp32-1732s019
pio run

# Build and upload
pio run --target upload

🎨 Recent Firmware Improvements

• Unified battery smoothing & percent logic
• Always-on Wi-Fi outline and disconnect indicator
• Removed legacy calibration for leaner build
• Overlap-safe layout for battery and Wi-Fi icons

Testing

🧪 Test Suite (Coming Soon)

A comprehensive test suite is planned. Current testing workflow:

• Manual testing with real devices
• TypeScript type checking (npm run typecheck)
• Linting (npm run lint)
• Code formatting (npm run format)

Production Build

To build and run TallyHub in production:

# Build the project
npm run build

# Run production server
NODE_ENV=production LOG_LEVEL=info node dist/index.js

# Or use the CLI
NODE_ENV=production npx tallyhub