samastek/Tempering-Machine-Control-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive data management and configuration specification documentation; introduce analysis of tempering machine control system architecture and behavior

Browse Source
This commit is contained in:
Sami Alzein
2025-08-06 21:35:53 +02:00
parent f539289f45
commit 4a49f78da4
6 changed files with 2338 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
docs/02-hardware-communication.md Normal file
View File

@@ -0,0 +1,300 @@
# 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.