# Hardware Communication Specification

## Overview

The system communicates with industrial hardware using Modbus RTU protocol over RS-485 serial communication. This document details the communication architecture, protocols, and data structures.

## Communication Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                APPLICATION LAYER                           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│  │   Recipe    │ │   Motor     │ │     Temperature         │ │
│  │  Control    │ │  Control    │ │      Control            │ │
│  └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│               COMMUNICATION LAYER                          │
│                                                             │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐   │
│  │    Write    │────▶│    Queue    │────▶│    Read     │   │
│  │    Queue    │     │   Manager   │     │    Queue    │   │
│  └─────────────┘     └─────────────┘     └─────────────┘   │
│         │                   │                   │          │
│         └───────────────────┼───────────────────┘          │
│                             ▼                              │
│              ┌─────────────────────────────┐                │
│              │      Serial Thread          │                │
│              │    (Queue Processor)        │                │
│              └─────────────────────────────┘                │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│                 MODBUS RTU LAYER                           │
│                                                             │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│  │   Message   │ │     CRC     │ │      Timeout            │ │
│  │  Framing    │ │ Validation  │ │     Handling            │ │
│  └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                               │
┌─────────────────────────────────────────────────────────────┐
│                PHYSICAL LAYER                              │
│                                                             │
│        ┌─────────────┐              ┌─────────────┐         │
│        │ Serial Port │─────RS485────│  Hardware   │         │
│        │   Driver    │              │ Controller  │         │
│        └─────────────┘              └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

## Modbus RTU Implementation

### Supported Function Codes

| Function Code | Name | Purpose | Usage in System |
|---------------|------|---------|-----------------|
| 0x01 | Read Coils | Read discrete outputs | Motor status monitoring |
| 0x03 | Read Holding Registers | Read output registers | System status, setpoints |
| 0x04 | Read Input Registers | Read input registers | Temperature sensors, digital inputs |
| 0x05 | Write Single Coil | Write single output | Individual motor control |
| 0x06 | Write Single Register | Write single register | Individual setpoint updates |
| 0x0F | Write Multiple Coils | Write multiple outputs | Batch motor control |
| 0x10 | Write Multiple Registers | Write multiple registers | Configuration updates |

### Message Structure

```
Standard Modbus RTU Frame:
┌──────────┬─────────────┬──────────────┬──────────┬──────────┐
│ Slave ID │ Function    │     Data     │  CRC-16  │   End    │
│ (1 byte) │ Code        │   (N bytes)  │ (2 bytes)│  Frame   │
│          │ (1 byte)    │              │          │          │
└──────────┴─────────────┴──────────────┴──────────┴──────────┘

Example - Read Input Registers:
┌──────────┬─────────────┬──────────┬──────────┬──────────┬──────────┐
│   0x01   │    0x04     │  0x00    │  0x00    │  0x00    │  0x12    │
│ Slave ID │ Read Input  │ Start    │ Start    │ Number   │ Number   │
│          │ Registers   │ Addr Hi  │ Addr Lo  │ Regs Hi  │ Regs Lo  │
└──────────┴─────────────┴──────────┴──────────┴──────────┴──────────┘
```

### CRC-16 Calculation

The system implements Modbus standard CRC-16 calculation:

```
Algorithm: CRC-16-IBM (polynomial 0xA001)
Initial Value: 0xFFFF
Final XOR: None
Bit Order: LSB first
```

## Register Mapping

### Holding Registers (Write/Read)

| Address | Name | Type | Range | Units | Purpose |
|---------|------|------|-------|-------|---------|
| 0 | Reset Error | uint16 | 0-65535 | Bitfield | Error reset flags |
| 1 | HV Output | uint16 | 0-65535 | Bitfield | High voltage outputs |
| 2 | LV Output | uint16 | 0-65535 | Bitfield | Low voltage outputs |
| 3 | Motor Control | uint16 | 0-65535 | Bitfield | Motor on/off states |
| 4-5 | Set Temperature 1 | int32 | -10000 to 6500 | Deciselsius | Tank bottom heater |
| 6-7 | Set Temperature 2 | int32 | -10000 to 6500 | Deciselsius | Tank wall heater |
| 8-9 | Set Temperature 3 | int32 | -10000 to 6500 | Deciselsius | Pump heater |
| 10-11 | Set Temperature 4 | int32 | -10000 to 6500 | Deciselsius | Fountain heater |

### Input Registers (Read Only)

| Address | Name | Type | Range | Units | Purpose |
|---------|------|------|-------|-------|---------|
| 0 | Board Flags | uint16 | 0-65535 | Bitfield | System status flags |
| 1 | Input States | uint16 | 0-65535 | Bitfield | Digital input states |
| 2-4 | Grid Voltages | uint16 | 0-3000 | Volts | L1, L2, L3 voltages |
| 5 | Neutral Current | uint16 | 0-1000 | Deciselsius | Neutral line current |
| 6-7 | Motor Currents | uint16 | 0-1000 | Deciselsius | Motor 1, 2 currents |
| 8-11 | Temperatures | int16 | -1400 to 650 | Deciselsius | T1, T2, T3, T4 readings |
| 12-13 | Analog Inputs | uint16 | 0-65535 | Raw ADC | General purpose analog |
| 14-15 | System Temps | uint16 | 0-1000 | Deciselsius | Heat sink, internal |
| 16 | External Power | uint16 | 0-1000 | Deciselsius | External power voltage |
| 17 | Grid Frequency | uint16 | 0-1000 | Decideciseconds | Line frequency |

## Hardware Mapping System

### Mapping Configuration

The system uses a CSV-based mapping file to associate logical names with hardware addresses:

```csv
Id,Name,Address,IsRead,BitNumbers
1,Pedal,1,1,0
2,Cover Sensor,1,1,1
3,E-Stop,1,1,2
4,Tank Bottom Temp,8,1,8
5,Tank Wall Temp,9,1,9
6,Pump Temp,10,1,10
7,Fountain Temp,11,1,11
8,Vibrator Heater,2,0,0
9,Mold Heater,2,0,1
10,Alarm,2,0,2
11,Vibrator,1,0,0
12,Mixer,3,0,0
13,Pump,3,0,1
```

### Bit Field Operations

Motor control uses bit manipulation for individual motor control:

```
Motor Control Register (Address 3):
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│15 │14 │13 │12 │11 │10 │ 9 │ 8 │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
  │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │
  │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   └─ Mixer
  │   │   │   │   │   │   │   │   │   │   │   │   │   │   └───── Pump
  │   │   │   │   │   │   │   │   │   │   │   │   │   └─────── Helix
  │   │   │   │   │   │   │   │   │   │   │   │   └─────────── Reserved
  │   │   │   │   │   │   │   │   │   │   │   └───────────────── Reserved
  └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴─────────────────────── Reserved
```

### Temperature Data Format

Temperature values are transmitted as signed 16-bit integers in deciselsius:

```
Temperature Conversion:
Raw Value: -273 (deciselsius)
Actual Temperature: -27.3°C

Special Values:
-10000: Heater disabled/off
Values > 6500: Invalid/error condition
Values < -1400: Sensor error
```

## Communication Timing

### Message Scheduling

```
Communication Timeline:
┌─────────────────────────────────────────────────────────────┐
│                    Message Cycle                           │
│                                                             │
│ ┌─────┐    ┌──────┐    ┌─────┐    ┌──────────────────────┐ │
│ │Write│    │ 4-Char│    │Read │    │     Wait for Next    │ │
│ │ Req │    │ Delay │    │Resp │    │       Cycle          │ │
│ └─────┘    └──────┘    └─────┘    └──────────────────────┘ │
│    │          │          │                 │              │
│   10ms      varies      50ms          configurable        │
│                │                                           │
│         Based on baud rate                                 │
│         (4 chars * 11 bits/char) / baud                   │
└─────────────────────────────────────────────────────────────┘
```

### Retry Logic

```
Retry Sequence:
Attempt 1 ──┐
            │ Failure
            ▼
         Wait 1s ──┐
                   │
Attempt 2 ─────────┘──┐
                      │ Failure  
                      ▼
                   Wait 1s ──┐
                             │
Attempt 3 ───────────────────┘──┐
                                │ Failure
                                ▼
                            Set Error Flag
                            (Communication Timeout)
```

### Error Detection and Recovery

| Error Condition | Detection Method | Recovery Action |
|-----------------|------------------|-----------------|
| CRC Mismatch | Frame validation | Immediate retry |
| Timeout | No response in 1s | Retry up to 3 times |
| Invalid Length | Frame size check | Discard and retry |
| Communication Loss | 3+ consecutive failures | Set error flag, continue retrying |
| Port Error | Serial port exception | Reset port, retry |

## Queue Management

### Write Queue (Priority Operations)

```
Write Queue Structure:
┌─────────────────────────────────────────────────────────────┐
│ Priority: Motor Control, Temperature Setpoints, Errors     │
│                                                             │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │   Motor     │ │ Temperature │ │       Error             │ │
│ │  Commands   │ │  Setpoints  │ │      Reset              │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│       │               │                     │              │
│       └───────────────┼─────────────────────┘              │
│                       ▼                                    │
│              ┌─────────────────┐                           │
│              │ Serial Transmit │                           │
│              └─────────────────┘                           │
└─────────────────────────────────────────────────────────────┘
```

### Read Queue (Monitoring Operations)

```
Read Queue Structure:
┌─────────────────────────────────────────────────────────────┐
│ Regular Monitoring: Sensors, Status, Diagnostics          │
│                                                             │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Temperature │ │   Digital   │ │      Analog             │ │
│ │   Sensors   │ │   Inputs    │ │      Inputs             │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│       │               │                     │              │
│       └───────────────┼─────────────────────┘              │
│                       ▼                                    │
│              ┌─────────────────┐                           │
│              │ Process Response│                           │
│              └─────────────────┘                           │
└─────────────────────────────────────────────────────────────┘
```

## Configuration Parameters

### Serial Port Settings

| Parameter | Default | Range | Description |
|-----------|---------|-------|-------------|
| Baud Rate | 9600 | 1200-115200 | Communication speed |
| Data Bits | 8 | 7-8 | Character size |
| Stop Bits | 1 | 1-2 | Frame termination |
| Parity | None | None/Odd/Even/Mark/Space | Error detection |
| Timeout | 1000ms | 100-5000ms | Response timeout |
| Retry Count | 3 | 1-10 | Maximum retry attempts |
| Send Interval | 100ms | 50-1000ms | Minimum time between messages |

### Modbus Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| Slave ID | 1 | Target device address |
| Function Codes | 0x01,0x03,0x04,0x05,0x06,0x0F,0x10 | Supported operations |
| Max Register Count | 125 | Maximum registers per request |
| CRC Validation | Enabled | Frame integrity checking |
| Broadcast Support | Disabled | Multi-device communication |

This communication specification provides the complete details needed to implement a robust Modbus RTU communication system for the tempering machine hardware interface.
