javi-forge 1.1.0 → 1.3.0

package/ai-config/skills/systems-iot/modbus-protocol/SKILL.md

@@ -1,410 +0,0 @@
----
-name: modbus-protocol
-description: >
-  Modbus industrial protocol implementation in Rust, Go, and Python.
-  Trigger: modbus, plc, scada, industrial protocol, registers, coils
-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-metadata:
-  author: plataforma-industrial
-  version: "2.0"
-  tags: [industrial, modbus, plc, sensors, protocol]
-  language: rust
-  updated: "2026-02"
----
-
-# Modbus Protocol
-
-> Industrial Modbus TCP/RTU implementation for sensor communication
-
-## When to Use
-
-- [ ] Reading data from PLCs (Siemens, Allen-Bradley, Schneider)
-- [ ] Communicating with industrial sensors
-- [ ] Building SCADA/gateway systems
-- [ ] Implementing OT (Operational Technology) integrations
-
-## Stack
-
-```yaml
-# Rust
-tokio-modbus: "0.13+"
-
-# Go
-github.com/simonvetter/modbus: latest
-
-# Python
-pymodbus: "3.6+"
-```
-
-## Modbus Fundamentals
-
-### Register Types
-
-| Type | Address Range | Access | Use Case |
-|------|---------------|--------|----------|
-| Coils | 00001-09999 | R/W | Digital outputs (on/off) |
-| Discrete Inputs | 10001-19999 | R | Digital inputs (read-only) |
-| Input Registers | 30001-39999 | R | Analog inputs (16-bit) |
-| Holding Registers | 40001-49999 | R/W | Configuration & data |
-
-### Function Codes
-
-| Code | Function | Description |
-|------|----------|-------------|
-| 01 | Read Coils | Read multiple digital outputs |
-| 02 | Read Discrete Inputs | Read digital inputs |
-| 03 | Read Holding Registers | Read configuration registers |
-| 04 | Read Input Registers | Read analog inputs |
-| 05 | Write Single Coil | Set single output |
-| 06 | Write Single Register | Write one register |
-| 16 | Write Multiple Registers | Write block of registers |
-
-## Rust Implementation
-
-### Client Setup
-
-```rust
-use tokio_modbus::prelude::*;
-use tokio_modbus::client::tcp;
-use std::net::SocketAddr;
-use tokio::time::{timeout, Duration};
-
-pub struct ModbusClient {
-    ctx: client::Context,
-    timeout_duration: Duration,
-}
-
-impl ModbusClient {
-    pub async fn connect(addr: SocketAddr, slave_id: u8) -> Result<Self, ModbusError> {
-        let ctx = tcp::connect_slave(addr, Slave(slave_id)).await?;
-        Ok(Self { ctx, timeout_duration: Duration::from_secs(5) })
-    }
-
-    pub async fn read_holding_registers(&mut self, address: u16, count: u16) -> Result<Vec<u16>> {
-        timeout(self.timeout_duration, self.ctx.read_holding_registers(address, count))
-            .await
-            .map_err(|_| ModbusError::Timeout)?
-            .map_err(ModbusError::from)
-    }
-
-    pub async fn write_single_register(&mut self, address: u16, value: u16) -> Result<()> {
-        timeout(self.timeout_duration, self.ctx.write_single_register(address, value))
-            .await
-            .map_err(|_| ModbusError::Timeout)?
-            .map_err(ModbusError::from)
-    }
-}
-```
-
-### Data Type Conversions
-
-```rust
-/// Two 16-bit registers to f32 (big-endian)
-pub fn registers_to_f32(regs: &[u16]) -> f32 {
-    let bytes = [
-        (regs[0] >> 8) as u8, regs[0] as u8,
-        (regs[1] >> 8) as u8, regs[1] as u8,
-    ];
-    f32::from_be_bytes(bytes)
-}
-
-/// Two 16-bit registers to f32 (little-endian, swapped)
-pub fn registers_to_f32_le(regs: &[u16]) -> f32 {
-    let bytes = [
-        regs[1] as u8, (regs[1] >> 8) as u8,
-        regs[0] as u8, (regs[0] >> 8) as u8,
-    ];
-    f32::from_le_bytes(bytes)
-}
-
-/// f32 to two 16-bit registers
-pub fn f32_to_registers(value: f32) -> [u16; 2] {
-    let bytes = value.to_be_bytes();
-    [
-        ((bytes[0] as u16) << 8) | (bytes[1] as u16),
-        ((bytes[2] as u16) << 8) | (bytes[3] as u16),
-    ]
-}
-
-/// Scale raw value to engineering units
-pub fn scale_value(raw: u16, min_raw: u16, max_raw: u16, min_eng: f32, max_eng: f32) -> f32 {
-    let range_raw = (max_raw - min_raw) as f32;
-    let range_eng = max_eng - min_eng;
-    let normalized = (raw - min_raw) as f32 / range_raw;
-    min_eng + (normalized * range_eng)
-}
-```
-
-### Sensor Reader
-
-```rust
-#[derive(Debug, Clone)]
-pub struct SensorConfig {
-    pub id: String,
-    pub name: String,
-    pub address: u16,
-    pub data_type: DataType,
-    pub unit: String,
-    pub scale: Option<Scale>,
-}
-
-#[derive(Debug, Clone)]
-pub enum DataType {
-    UInt16,
-    Int16,
-    Float32,
-    Float32LE,
-}
-
-#[derive(Debug, Clone)]
-pub struct SensorReading {
-    pub sensor_id: String,
-    pub value: f64,
-    pub quality: u8,  // 192=Good, 128=Uncertain, 0=Bad
-    pub timestamp: i64,
-}
-
-pub struct SensorReader {
-    client: ModbusClient,
-    sensors: Vec<SensorConfig>,
-}
-
-impl SensorReader {
-    pub async fn read_sensor(&mut self, sensor: &SensorConfig) -> Result<SensorReading> {
-        let count = match sensor.data_type {
-            DataType::UInt16 | DataType::Int16 => 1,
-            DataType::Float32 | DataType::Float32LE => 2,
-        };
-
-        let registers = self.client.read_holding_registers(sensor.address, count).await?;
-
-        let raw_value: f64 = match sensor.data_type {
-            DataType::UInt16 => registers[0] as f64,
-            DataType::Int16 => (registers[0] as i16) as f64,
-            DataType::Float32 => registers_to_f32(&registers) as f64,
-            DataType::Float32LE => registers_to_f32_le(&registers) as f64,
-        };
-
-        let value = if let Some(scale) = &sensor.scale {
-            scale_value(raw_value as u16, scale.min_raw, scale.max_raw, scale.min_eng, scale.max_eng) as f64
-        } else {
-            raw_value
-        };
-
-        Ok(SensorReading {
-            sensor_id: sensor.id.clone(),
-            value,
-            quality: 192, // Good
-            timestamp: chrono::Utc::now().timestamp_millis(),
-        })
-    }
-}
-```
-
-## Go Implementation
-
-```go
-package modbus
-
-import (
-    "encoding/binary"
-    "math"
-    "sync"
-    "time"
-
-    "github.com/simonvetter/modbus"
-)
-
-type Client struct {
-    client *modbus.ModbusClient
-    mu     sync.Mutex
-}
-
-func NewClient(address string, slaveID uint8) (*Client, error) {
-    client, err := modbus.NewClient(&modbus.ClientConfiguration{
-        URL:     fmt.Sprintf("tcp://%s", address),
-        Speed:   19200,
-        Timeout: 5 * time.Second,
-    })
-    if err != nil { return nil, err }
-
-    if err := client.Open(); err != nil { return nil, err }
-    client.SetUnitId(slaveID)
-
-    return &Client{client: client}, nil
-}
-
-func (c *Client) ReadHoldingRegisters(address, count uint16) ([]uint16, error) {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    return c.client.ReadRegisters(address, count, modbus.HOLDING_REGISTER)
-}
-
-func RegistersToFloat32(regs []uint16) float32 {
-    bytes := make([]byte, 4)
-    binary.BigEndian.PutUint16(bytes[0:2], regs[0])
-    binary.BigEndian.PutUint16(bytes[2:4], regs[1])
-    return math.Float32frombits(binary.BigEndian.Uint32(bytes))
-}
-```
-
-## Python Implementation
-
-```python
-from pymodbus.client import AsyncModbusTcpClient
-from dataclasses import dataclass
-import struct
-
-@dataclass
-class SensorConfig:
-    id: str
-    address: int
-    data_type: str  # 'uint16', 'int16', 'float32'
-    unit: str
-
-class ModbusReader:
-    def __init__(self, host: str, port: int = 502, slave_id: int = 1):
-        self.host = host
-        self.port = port
-        self.slave_id = slave_id
-
-    async def connect(self):
-        self.client = AsyncModbusTcpClient(self.host, port=self.port)
-        await self.client.connect()
-
-    async def read_holding_registers(self, address: int, count: int):
-        result = await self.client.read_holding_registers(address, count, slave=self.slave_id)
-        return result.registers
-
-    async def read_sensor(self, config: SensorConfig) -> float:
-        count = 2 if 'float32' in config.data_type else 1
-        regs = await self.read_holding_registers(config.address, count)
-
-        if config.data_type == 'uint16':
-            return regs[0]
-        elif config.data_type == 'int16':
-            return struct.unpack('>h', struct.pack('>H', regs[0]))[0]
-        elif config.data_type == 'float32':
-            bytes_data = struct.pack('>HH', regs[0], regs[1])
-            return struct.unpack('>f', bytes_data)[0]
-```
-
-## PLC Address Maps
-
-### Siemens S7-1200/1500
-
-```yaml
-holding_registers:
-  40001: DB1.DBD0   # Float, first double word in DB1
-  40003: DB1.DBD4   # Float, second double word
-  40005: MW100      # Word memory
-
-coils:
-  00001: Q0.0       # Output bit 0.0
-  00002: Q0.1       # Output bit 0.1
-```
-
-### Allen-Bradley ControlLogix
-
-```yaml
-holding_registers:
-  40001: N7:0       # Integer file
-  40002: F8:0       # Float (uses 2 registers)
-```
-
-### Schneider Modicon
-
-```yaml
-holding_registers:
-  40001: %MW0       # Memory word 0
-  40003: %MF0       # Float (2 registers)
-```
-
-## Error Handling
-
-```rust
-pub fn modbus_error_description(code: u8) -> &'static str {
-    match code {
-        0x01 => "Illegal Function",
-        0x02 => "Illegal Data Address",
-        0x03 => "Illegal Data Value",
-        0x04 => "Slave Device Failure",
-        0x05 => "Acknowledge",
-        0x06 => "Slave Device Busy",
-        _ => "Unknown Error",
-    }
-}
-```
-
-## Best Practices
-
-### Batch Reads
-
-```rust
-// ✅ Single read for contiguous registers
-client.read_holding_registers(40001, 10).await?;
-
-// ❌ Multiple individual reads - slow!
-for addr in 40001..40011 {
-    client.read_holding_registers(addr, 1).await?;
-}
-```
-
-### Connection Reuse
-
-```rust
-// ✅ Reuse connection
-let client = ModbusClient::connect(addr, slave_id).await?;
-for _ in 0..100 {
-    client.read_holding_registers(addr, count).await?;
-}
-
-// ❌ New connection per read
-for _ in 0..100 {
-    let client = ModbusClient::connect(addr, slave_id).await?;
-    client.read_holding_registers(addr, count).await?;
-}
-```
-
-### Polling Intervals
-
-| Sensor Type | Recommended Interval |
-|-------------|---------------------|
-| Vibration | 10-50ms |
-| Temperature/Pressure | 500ms-1s |
-| Level/Flow totals | 5-10s |
-
-## Quick Reference
-
-| Task | Rust |
-|------|------|
-| Read holding | `ctx.read_holding_registers(addr, count).await` |
-| Read input | `ctx.read_input_registers(addr, count).await` |
-| Write single | `ctx.write_single_register(addr, value).await` |
-| Write multiple | `ctx.write_multiple_registers(addr, &values).await` |
-| Read coils | `ctx.read_coils(addr, count).await` |
-
-## Quality Codes (OPC UA)
-
-| Code | Meaning |
-|------|---------|
-| 192 (0xC0) | Good |
-| 128 (0x80) | Uncertain |
-| 0 (0x00) | Bad |
-
-## Resources
-
-- [Modbus Specification](https://modbus.org/specs.php)
-- [tokio-modbus Docs](https://docs.rs/tokio-modbus)
-- [pymodbus Documentation](https://pymodbus.readthedocs.io/)
-
-## Related Skills
-
-- `mqtt-rumqttc`: Data forwarding to MQTT
-- `tokio-async`: Async polling patterns
-- `timescaledb`: Industrial data storage
-- `rust-systems`: Full Rust integration