TZEcosystem

19 Jan 2026

TZEcosystem

A unified ecosystem for the Tonnetz musical instrument family, featuring shared control architecture, web-based interfaces, and browser-based simulation.

Overview

TZEcosystem provides:

  • Shared firmware components for TZ5_30cm (no audio) and TZ7 (cap touch, audio)
  • Web-based control panel for parameter management and device coordination
  • Browser-based simulator (planned) for audio/visual demonstration and parameter tuning
  • Mesh-first networking enabling multi-device synchronization

Folder Structure

TZEcosystem/
├── docs/                    # Documentation
│   ├── architecture.md      # System architecture
│   ├── protocol.md          # Binary protocol specification
│   ├── configuration.md     # Configuration parameters
│   └── roadmap.md           # Future development plans
│
├── shared/                  # Shared firmware code
│   ├── tz_config.h          # Unified configuration structure
│   ├── tz_protocol.h        # Message protocol definitions
│   ├── tz_ca_engine.h       # Cellular automata engine
│   ├── tz_tonnetz.h         # 13x13 grid mapping
│   ├── tz_led.h             # FastLED abstraction
│   └── tz_network.h         # Network layer abstraction
│
├── firmware/
│   ├── TZ5_30cm/            # TZ5 variant (no audio)
│   └── TZ7/                 # TZ7 variant (cap touch, audio)
│
├── control-panel/           # Web control interface
│   ├── docker-compose.yml
│   ├── frontend/
│   ├── backend/
│   └── db/
│
└── simulator/               # Browser-based audiovisual simulator
    ├── index.html
    ├── js/
    └── css/

Quick Start

Firmware Development

  1. Install PlatformIO
  2. Navigate to desired firmware variant: 
    cd firmware/TZ5_30cm
# or
cd firmware/TZ7
  3. Build and upload: 
    pio run -t upload

Control Panel

  1. Install Docker and Docker Compose
  2. Navigate to control-panel: 
    cd control-panel
docker-compose up -d
  3. Access at http://localhost:3000

Simulator

See docs/simulator-requirements.md for scope and requirements. Implementation will live under simulator/.

Legacy Web Stack

The tonnetz_web_docker + TZ5_30cm_Hex pairing is the legacy PHP/MariaDB control pipeline. The new control panel in control-panel/ supersedes it, but compatibility endpoints are documented in docs/simulator-requirements.md for simulator parity testing.

Network Architecture

TZEcosystem uses a mesh-first architecture with graceful fallback:

  1. Mesh Mode (Primary): Devices sync via UDP broadcast on local network
  2. Server Mode (Optional): Central control panel for studio environments
  3. Standalone Mode: Single device, full local operation
  4. AP Mode: Device creates hotspot for configuration

Configuration

All configuration parameters are documented in docs/configuration.md. Key parameters include:

Parameter Type Description
bpm float Tempo in beats per minute
max_pop int Maximum active cells
min_pop int Minimum active cells
rate int CA update rate (ms)
note_duration int Note length (ms)
update_pattern enum Cell selection pattern
arp_mode enum Arpeggiator mode

Protocol

Binary protocol specification in docs/protocol.md. Magic bytes: 0x54 0x5A (“TZ”).

Packet types:

  • 0x01: Configuration
  • 0x02: State update
  • 0x03: Sync message

License

[Specify your license here]

Contributing

[Contribution guidelines]

Recent Activity

  • 18da50b basic tonnetz web sim working, plan developing for new user interface, and integ (2026-01-19)
  • d74be67 basic tonnetz web sim working, plan developing for new user interface, and integ (2026-01-19)

Languages

  • C: 34%
  • JavaScript: 32%
  • C++: 16%
  • HTML: 10%
  • CSS: 8%