Architecture & Core Concepts

Sources: Documentation/source/CLAUDE.md, accordionpilot/AccordionPilot/docs/ap-index.md, Documentation/source/MDNS_IMPLEMENTATION_SUMMARY.md

What is Accordion?

AccordionQ2 is a C# .NET embedded hardware control application running on a Raspberry Pi (ARM32/Linux). It hosts pluggable hardware modules (ESH1* series) and exposes all hardware signals and protocols (SCPI, Modbus, PMBus, HCI, I2C, SPI, UART, etc.) to remote clients over a network protocol server.

The name "Accordion" reflects its expandable, modular nature — you add or remove hardware modules and the system adapts automatically.

Three-Layer Architecture

┌─────────────────────────────────────────────────────┐
│  CLIENT LAYER                                        │
│  Accordion Pilot (GUI) · AccordionShell (CLI)        │
│  .NET API (AccordionQ2Client) · Python API           │
└──────────────────┬──────────────────────────────────┘
                   │  HTTP (WebApi :5000) or
                   │  proprietary ProtocolServer (:10000+)
┌──────────────────▼──────────────────────────────────┐
│  APPLICATION ENGINE (AccordionQ2 on Raspberry Pi)    │
│  ApplicationEngine · ModuleManager · HAL             │
│  mDNS Advertiser · NetworkManager config             │
└──────────────────┬──────────────────────────────────┘
                   │  I2C / SPI / UART / GPIO / etc.
┌──────────────────▼──────────────────────────────────┐
│  HARDWARE LAYER                                      │
│  ESH1* modules plugged into the Accordion backplane  │
└─────────────────────────────────────────────────────┘

Layer 1 — Hardware

Physical Accordion device with one or more ESH1 expansion modules* plugged into the backplane. Each module exposes signals over internal buses (I2C, SPI, GPIO).

See Hardware Modules for the full module catalogue.

Layer 2 — Application Engine

The core software that runs on the Raspberry Pi:

Layer 3 — Clients

The Channel Model

Everything in Accordion is a channel. A channel is a named, typed endpoint:

{ModuleIndex}.{ProductID}.{ChannelName}
e.g.  0.ESH10000590.ADC_CH0
      1.ESH10000025.GPIO_OUT_00

Channel Properties

Reading and Writing Values

All channel values are strings on the wire. The client is responsible for parsing (e.g. double.Parse(value)).

Read:   GET /api/resources/value?name=0.ESH10000590.ADC_CH0  →  "3.2987"
Write:  POST /api/resources/value/set  { name: "…", value: "2.5" }

Batch read/write is supported for efficiency — see the API reference.

Protocol Ports

All client libraries (AccordionShell, Pilot, .NET, Python) use the HTTP WebApi (port 5000). The binary protocol ports are used internally and by legacy integrations.

Service Discovery (mDNS)

Accordion devices self-advertise on the LAN using mDNS/DNS-SD (Bonjour/ZeroConf):

• Service type: _accordion._tcp.local
• Instance name: {ControllerType}-{Hostname} (e.g. AGENTQ2-agent64)
• Port: 10000
• TXT records: firmware version, app version, hostname, all protocol port numbers, operating mode

Clients can discover devices without knowing the IP address. The hostname is also resolvable: http://agent64.local:5000.

TTL is 4500 seconds (75 min) with automatic re-announcement at ~37.5 min intervals. On graceful shutdown, TTL=0 goodbye packets are sent to immediately remove the entry from all caches.

Full details: Network Configuration

Module Lifecycle

ApplicationEngine.Execute()
  → ModuleManager loads all enabled modules from config
  → Each module registers its channels with the HAL
  → HAL builds the channel map
  → ProtocolServer starts serving on ports 10000+
  → WebApi starts serving on port 5000
  → MdnsAdvertiser.AdvertiseDiscoveredModules() called
  → System is live

Modules can be loaded, unloaded, and reconfigured at runtime via the API without restarting the engine.