kbot experiments :)
This commit is contained in:
parent
533dbf3afa
commit
ffed55be4f
File diff suppressed because one or more lines are too long
125
docs-c/components/3PosAnalog.md
Normal file
125
docs-c/components/3PosAnalog.md
Normal file
@ -0,0 +1,125 @@
|
||||
---
|
||||
title: 3-Position Analog Switch Component
|
||||
description: Documentation for the Pos3Analog component that provides a 3-position switch interface with local and remote control modes
|
||||
keywords: [Pos3Analog, 3-position switch, modbus, esp32, analog input]
|
||||
---
|
||||
|
||||
## Pos3Analog
|
||||
|
||||
**Path**: [src/Pos3Analog.h](../../src/Pos3Analog.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Pos3Analog component provides functionality for a 3-position analog switch interface, supporting both local (hardware) and remote (Modbus) control. It reads the state of a physical switch through analog inputs and exposes the switch state via Modbus. The component can be configured to operate in local mode (reading physical inputs) or remote mode (controlled via Modbus).
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- **Hardware**:
|
||||
- Two analog input pins (upPin and downPin)
|
||||
- ESP-32 microcontroller
|
||||
|
||||
- **Software**:
|
||||
- Platform.io build environment
|
||||
- C++17 compatible compiler
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Reads a 3-position switch (UP, MIDDLE, DOWN) using two analog inputs
|
||||
- Supports two control modes: LOCAL (hardware) and REMOTE (Modbus)
|
||||
- Provides Modbus register interface for reading the current position
|
||||
- Allows remote control of the switch position
|
||||
- Configurable Modbus address for integration with industrial systems
|
||||
- Debounced analog input reading with configurable interval
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - For logging functionality
|
||||
- [Component](../../src/Component.h) - Base component class
|
||||
- [xmath](../../src/xmath.h) - For range checking and math utilities
|
||||
- [ModbusTCP](../../src/modbus/ModbusTCP.h) - For Modbus communication
|
||||
- [config.h](../../src/config.h) - For configuration constants
|
||||
- [config-modbus.h](../../src/config-modbus.h) - For Modbus-specific configurations
|
||||
- [enums.h](../../src/enums.h) - For enumerations used by the component
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Pos3Analog --> Component
|
||||
Pos3Analog --> xmath
|
||||
Pos3Analog --> ModbusTCP
|
||||
Pos3Analog --> ArduinoLog
|
||||
Component --> ArduinoLog
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Setup
|
||||
Setup --> Idle
|
||||
Idle --> ReadLocal: If ControlMode==LOCAL
|
||||
Idle --> ReadRemote: If ControlMode==REMOTE
|
||||
ReadLocal --> UpdateState: If position changed
|
||||
ReadRemote --> UpdateState: If position changed
|
||||
UpdateState --> NotifyChange
|
||||
NotifyChange --> Idle
|
||||
Idle --> ProcessModbus: ModbusRequest
|
||||
ProcessModbus --> ChangeMode: Write to Mode Register
|
||||
ProcessModbus --> ChangeRemoteValue: Write to RemoteValue Register
|
||||
ProcessModbus --> ReturnCurrentValue: Read from Value Register
|
||||
ChangeMode --> Idle
|
||||
ChangeRemoteValue --> UpdateState: If Remote Mode & value changed
|
||||
ReturnCurrentValue --> Idle
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing hysteresis for analog readings to prevent flickering between states
|
||||
- Optimize the loop interval for different application scenarios to balance responsiveness and CPU usage
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add bounds checking on Modbus register access to prevent potential overflows
|
||||
- Consider adding a validation mechanism for state changes to prevent rapid oscillations
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with industrial Modbus protocol standards for wider compatibility
|
||||
- Document conformance to RS-485 electrical standards if used in that context
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use pull-up/pull-down resistors on the analog input pins for more reliable readings
|
||||
- Configure appropriate thresholds in config.h for the specific analog sensors being used
|
||||
- Implement error handling for the case of both UP and DOWN inputs being active
|
||||
- Consider adding a debounce mechanism for the switch position to prevent oscillation
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example demonstrates how to initialize and add a Pos3Analog component to your application:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_POS3_ANALOG_0_UP
|
||||
pos3Analog_0 = new Pos3Analog(
|
||||
this, // owner
|
||||
PIN_POS3_ANALOG_0_UP, // upPin
|
||||
PIN_POS3_ANALOG_0_DOWN,// downPin
|
||||
ID_POS3_ANALOG_0, // id
|
||||
POS3_ANALOG_0_MB_ADDR // modbusAddress
|
||||
);
|
||||
if (pos3Analog_0)
|
||||
{
|
||||
components.push_back(pos3Analog_0);
|
||||
Log.infoln(F("Pos3Analog_0 initialized. UpPin:%d, DownPin:%d, ID:%d, MB:%d"),
|
||||
PIN_POS3_ANALOG_0_UP, PIN_POS3_ANALOG_0_DOWN,
|
||||
ID_POS3_ANALOG_0, POS3_ANALOG_0_MB_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("Pos3Analog_0 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
116
docs-c/components/AnalogLevelSwitch.md
Normal file
116
docs-c/components/AnalogLevelSwitch.md
Normal file
@ -0,0 +1,116 @@
|
||||
---
|
||||
title: "Analog Level Switch Component Documentation"
|
||||
description: "Documentation for the AnalogLevelSwitch component, which reads analog inputs as multi-position switches"
|
||||
keywords: "ESP-32, analog, level switch, multi-position switch, modbus, Arduino, embedded"
|
||||
---
|
||||
|
||||
## Analog Level Switch
|
||||
|
||||
**Path**: [`src/AnalogLevelSwitch.cpp`](../src/AnalogLevelSwitch.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Analog Level Switch component reads an analog input pin and interprets the voltage as a discrete position or "slot". This is useful for interfacing with multi-position switches, potentiometers, or resistor networks connected to an analog input. The component provides smooth reading with configurable debouncing, hysteresis, and auto-calibration for reliable slot detection.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- An analog input pin connected to a voltage divider circuit
|
||||
- Appropriate resistor selection for desired voltage levels (detailed guidance provided in header file)
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Converts analog readings into discrete position slots
|
||||
- Configurable number of positions/slots (up to 32 by default)
|
||||
- Adjustable ADC value offset and step size per slot
|
||||
- Smoothing with moving average or exponential moving average
|
||||
- Configurable debouncing and hysteresis to prevent position flickering
|
||||
- Modbus integration with registers for current level and raw values
|
||||
- Individual slot state monitoring as Modbus coils
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - For logging capabilities
|
||||
- [Component](../src/Component.h) - Base component class
|
||||
- [ModbusTCP](../src/modbus/ModbusTCP.h) - For Modbus communication
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
AnalogLevelSwitch --> Component
|
||||
AnalogLevelSwitch --> ModbusTCP
|
||||
AnalogLevelSwitch --> ArduinoLog
|
||||
Component --> App
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The AnalogLevelSwitch reads the analog input at regular intervals, applies smoothing, debouncing, and then maps the analog value to a discrete slot.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialize
|
||||
Initialize --> ReadAnalog
|
||||
ReadAnalog --> SmoothValues
|
||||
SmoothValues --> DetermineSlot
|
||||
DetermineSlot --> Debounce
|
||||
Debounce --> StateChanged: n confirmations
|
||||
Debounce --> ReadAnalog: not confirmed
|
||||
StateChanged --> NotifyChange
|
||||
NotifyChange --> ReadAnalog
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Review smoothing algorithm choice based on application requirements (MA vs EMA)
|
||||
- Consider using hardware filtering for high-noise environments
|
||||
- Optimize ADC reading intervals based on use case
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Validate Modbus access controls to prevent unauthorized writes
|
||||
- Consider adding range validation for configuration parameters
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure ADC readings are within the ESP-32's input voltage specifications
|
||||
- Review compliance with relevant industrial standards if used in regulated environments
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- For optimal performance, use 1% or better tolerance resistors in voltage divider
|
||||
- Keep equivalent resistance of voltage divider relatively low (1k-100k range) to ensure ADC accuracy
|
||||
- Be mindful of resistor tolerance and ADC non-linearity when designing circuits
|
||||
- Use the resistor calculation guidance in the header file to design appropriate circuits
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_ANALOG_LEVEL_SWITCH
|
||||
analogLevelSwitch = new AnalogLevelSwitch(
|
||||
this, // owner
|
||||
PIN_ANALOG_LEVEL_SWITCH, // analogPin
|
||||
ALS_NUMBER_OF_LEVELS, // numLevels
|
||||
ALS_LEVEL_STEP, // levelStep
|
||||
ALS_ADC_VALUE_OFFSET, // adcValueOffset
|
||||
ID_ANALOG_LEVEL_SWITCH, // id
|
||||
ALS_MODBUS_ADDR // modbusAddress
|
||||
);
|
||||
|
||||
if (analogLevelSwitch)
|
||||
{
|
||||
components.push_back(analogLevelSwitch);
|
||||
Log.infoln(F("AnalogLevelSwitch initialized. Pin:%d, Levels:%d, Step:%d, Offset:%d, ID:%d, MB:%d"),
|
||||
PIN_ANALOG_LEVEL_SWITCH, ALS_NUMBER_OF_LEVELS, ALS_LEVEL_STEP,
|
||||
ALS_ADC_VALUE_OFFSET, ID_ANALOG_LEVEL_SWITCH, ALS_MODBUS_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("AnalogLevelSwitch initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
The component is specifically designed for multi-position switches using voltage dividers. The header file includes detailed information on the resistor selection process for creating a voltage divider setup that can reliably detect different switch positions.
|
||||
128
docs-c/components/Extruder.md
Normal file
128
docs-c/components/Extruder.md
Normal file
@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "Modbus485 Component"
|
||||
description: "A full-featured Modbus RTU master client implementation for ESP-32 devices, adding extensive error handling and logging."
|
||||
keywords: ["Modbus", "RS485", "ESP32", "industrial", "communication", "RTU"]
|
||||
---
|
||||
|
||||
## Modbus485
|
||||
|
||||
**Path**: [`src/modbus485.h`](../src/modbus485.h)
|
||||
|
||||
**Revision History**:
|
||||
- Initial documentation
|
||||
|
||||
A robust Modbus RTU communication component supporting RS-485 electrical interface for ESP-32 devices. This implementation features comprehensive error handling, logging, and state management, making it suitable for industrial applications requiring reliable communication.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Hardware:
|
||||
- RS-485 transceiver (e.g., MAX485)
|
||||
- UART TX pin
|
||||
- UART RX pin
|
||||
- DE/RE pin for direction control
|
||||
- Software:
|
||||
- HardwareSerial
|
||||
- ArduinoLog or similar for logging
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Full Modbus RTU master client implementation
|
||||
- Configurable baud rate, parity, and stop bits
|
||||
- Support for multiple read and write function codes
|
||||
- Automatic transaction ID management
|
||||
- Comprehensive error handling and reporting
|
||||
- Response timeout management
|
||||
- Debug logging
|
||||
- Modbus frame validation (CRC16)
|
||||
- State machine design for reliable operation
|
||||
- Supports single and block operations for coils, discrete inputs, holding registers and input registers
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
||||
- [Component](../src/component.h)
|
||||
- [EventManager](../src/event_manager.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Modbus485 --> Component
|
||||
Modbus485 --> EventManager
|
||||
Modbus485 --> ArduinoLog
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> IDLE
|
||||
|
||||
IDLE --> WAITING_TO_SEND: request initiated
|
||||
WAITING_TO_SEND --> SENDING: line ready
|
||||
SENDING --> WAITING_FOR_RESPONSE: frame sent
|
||||
WAITING_FOR_RESPONSE --> PROCESSING_RESPONSE: response received
|
||||
WAITING_FOR_RESPONSE --> TIMEOUT_ERROR: timeout
|
||||
|
||||
PROCESSING_RESPONSE --> IDLE: success
|
||||
PROCESSING_RESPONSE --> ERROR: validation failed
|
||||
|
||||
TIMEOUT_ERROR --> IDLE: reset
|
||||
ERROR --> IDLE: reset
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing a response parser to handle partial responses
|
||||
- Add transaction queuing to handle multiple concurrent requests
|
||||
- Optimize memory usage for constrained devices
|
||||
- Add retry mechanism for failed requests
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement message authentication for critical operations
|
||||
- Consider encryption for sensitive data transmission
|
||||
- Add access control mechanisms for write operations
|
||||
- Implement session timeouts for maintaining connection state
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure full compliance with Modbus RTU specification
|
||||
- Validate against Modbus conformance test suite
|
||||
- Document compatibility with specific Modbus devices
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use proper shielded cables for RS-485 communication
|
||||
- Implement proper termination resistors on the RS-485 bus
|
||||
- Consider using optically isolated RS-485 transceivers in noisy environments
|
||||
- Monitor response times and adjust timeouts accordingly
|
||||
- Implement application-level heartbeats for critical connections
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_RS485_DE
|
||||
modbus485 = new Modbus485(
|
||||
this, // owner
|
||||
PIN_RS485_TX, // TX pin
|
||||
PIN_RS485_RX, // RX pin
|
||||
PIN_RS485_DE, // DE/RE pin
|
||||
RS485_BAUDRATE, // baud rate
|
||||
RS485_CONFIG // UART configuration
|
||||
);
|
||||
|
||||
if (modbus485) {
|
||||
components.push_back(modbus485);
|
||||
Log.infoln(F("Modbus485 initialized. TX:%d, RX:%d, DE:%d, Baud:%d"),
|
||||
PIN_RS485_TX, PIN_RS485_RX, PIN_RS485_DE, RS485_BAUDRATE);
|
||||
} else {
|
||||
Log.errorln(F("Modbus485 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
- [Modbus Protocol Specification](https://modbus.org/specs.php)
|
||||
- [Modbus RTU Tutorial](https://www.simplymodbus.ca/FAQ.htm)
|
||||
120
docs-c/components/GPIO.md
Normal file
120
docs-c/components/GPIO.md
Normal file
@ -0,0 +1,120 @@
|
||||
---
|
||||
title: "ModbusRTU"
|
||||
description: "ESP-32 industrial Modbus-485 implementation for bidirectional communication"
|
||||
keywords: ["modbus", "rtu", "485", "esp32", "industrial", "communication", "protocol"]
|
||||
---
|
||||
|
||||
## ModbusRTU
|
||||
|
||||
**Path**: [`src/modbusRTU.h`](../../src/modbusRTU.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
ModbusRTU is a comprehensive implementation of the Modbus RTU protocol over RS-485 for ESP32 devices. It provides a robust, industrial-grade solution for bidirectional communication between master and slave devices, supporting both master functionality for querying other devices and slave functionality for responding to external queries.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- **Hardware**:
|
||||
- RS-485 transceiver (e.g., MAX485)
|
||||
- RX pin (configured in `pins_arduino.h`)
|
||||
- TX pin (configured in `pins_arduino.h`)
|
||||
- DE/RE pin for RS-485 direction control
|
||||
|
||||
- **Software**:
|
||||
- Platform.io with ESP32 support
|
||||
- C17 compiler support
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Supports both Modbus master and slave functionalities
|
||||
- Implements standard Modbus function codes (3, 4, 6, 16)
|
||||
- Automatic CRC calculation and validation
|
||||
- Configurable timeouts and retry mechanisms
|
||||
- Interrupt-driven communication with hardware buffer
|
||||
- Thread-safe operation
|
||||
- Extensible register mapping system
|
||||
- Support for various data types (uint16_t, float, etc.)
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [`ArduinoLog`](https://github.com/thijse/Arduino-Log)
|
||||
- [`component.h`](../../src/component.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
ModbusRTU --> Component
|
||||
ModbusRTU --> ArduinoLog
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Transmitting: Send Request/Response
|
||||
Transmitting --> Waiting: Master Mode
|
||||
Transmitting --> Idle: Slave Mode
|
||||
Waiting --> Processing: Receive Response
|
||||
Waiting --> Timeout: No Response
|
||||
Processing --> Idle: Success/Error
|
||||
Timeout --> Retry: Retries Left
|
||||
Timeout --> Idle: Max Retries
|
||||
Retry --> Transmitting
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing a more efficient buffer management system to reduce memory usage
|
||||
- Optimize CRC calculation for speed using lookup tables
|
||||
- Evaluate interrupt priorities to ensure timely processing of incoming data
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement message authentication to prevent unauthorized commands
|
||||
- Add support for encrypted Modbus communication where security is critical
|
||||
- Consider implementing access control lists for sensitive register operations
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Complete full compliance with Modbus RTU specification
|
||||
- Add support for additional function codes as needed for specific applications
|
||||
- Ensure timing requirements meet the Modbus specification under all operating conditions
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use shielded twisted pair cables for RS-485 communication to maximize reliability
|
||||
- Implement proper line termination (120Ω) at both ends of the RS-485 bus
|
||||
- Consider using galvanic isolation for the RS-485 transceiver in noisy environments
|
||||
- Regularly test communication with various slave devices to ensure compatibility
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example shows how to initialize and mount the ModbusRTU component in master mode:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_RS485_DE
|
||||
modbus = new ModbusRTU(
|
||||
this, // owner
|
||||
SERIAL_RS485, // serial port (defined in pins_arduino.h)
|
||||
PIN_RS485_DE, // direction control pin
|
||||
MODBUS_BAUD_RATE, // baud rate (typically 9600, 19200, or 115200)
|
||||
SERIAL_8N1, // data format (8 bits, no parity, 1 stop bit)
|
||||
1 // device ID for slave mode
|
||||
);
|
||||
|
||||
if (modbus)
|
||||
{
|
||||
components.push_back(modbus);
|
||||
Log.infoln(F("ModbusRTU initialized. DE/RE Pin: %d, Baud: %d, ID: %d"),
|
||||
PIN_RS485_DE, MODBUS_BAUD_RATE, 1);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("ModbusRTU initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
118
docs-c/components/Joystick.md
Normal file
118
docs-c/components/Joystick.md
Normal file
@ -0,0 +1,118 @@
|
||||
---
|
||||
title: "Joystick 4-Position Component"
|
||||
description: "Documentation for the Joystick component, a 4-position joystick controller with local and remote operation modes."
|
||||
keywords: "joystick, ESP32, modbus, component, controller, input device"
|
||||
---
|
||||
|
||||
## Joystick
|
||||
|
||||
**Path**: [`src/components/Joystick.cpp`](../../src/components/Joystick.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Joystick component provides an interface for a 4-position joystick (up, down, left, right) with support for both local physical operation and remote control via Modbus. It features position debouncing for reliable readings, position state tracking, and seamless switching between local and remote operation modes.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Four GPIO pins for joystick inputs (up, down, left, right)
|
||||
- Pull-up resistors (internal or external) for each input
|
||||
- Modbus support for remote operation
|
||||
|
||||
## FEATURES
|
||||
|
||||
- 5 distinct positions: UP, DOWN, LEFT, RIGHT, and CENTER
|
||||
- Configurable debouncing for reliable position readings
|
||||
- Position state tracking with timing information
|
||||
- Switchable operation modes:
|
||||
- LOCAL: reads physical joystick position
|
||||
- REMOTE: accepts position commands via Modbus
|
||||
- Complete Modbus integration
|
||||
- Position holding time tracking
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
||||
- [ModbusTCP](../../src/modbus/ModbusTCP.h)
|
||||
- [Component](../../src/Component.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Joystick --> Component
|
||||
Joystick --> ModbusTCP
|
||||
Joystick --> ArduinoLog
|
||||
Component --> ArduinoLog
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Setup
|
||||
Setup --> LocalMode
|
||||
Setup --> RemoteMode
|
||||
|
||||
LocalMode --> ReadPosition
|
||||
LocalMode --> RemoteMode: setMode(REMOTE)
|
||||
|
||||
ReadPosition --> Debouncing: useDebouncing true
|
||||
ReadPosition --> UpdatePosition: useDebouncing false
|
||||
|
||||
Debouncing --> UpdatePosition: confirmCount >= threshold
|
||||
UpdatePosition --> NotifyChange: position changed
|
||||
|
||||
RemoteMode --> LocalMode: setMode(LOCAL)
|
||||
RemoteMode --> OverridePosition: setOverridePosition()
|
||||
OverridePosition --> NotifyChange
|
||||
|
||||
NotifyChange --> LocalMode
|
||||
NotifyChange --> RemoteMode
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider optimizing the debouncing algorithm for specific application needs
|
||||
- Evaluate if READ_INTERVAL_MS (25ms) can be adjusted based on application requirements
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement input validation for Modbus commands
|
||||
- Consider adding authentication for remote mode switching
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with relevant industrial control standards
|
||||
- Review electrical safety requirements for the connected joystick hardware
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use hardware debouncing circuits when possible to reduce CPU load
|
||||
- Implement additional position combinations if needed (e.g., diagonal positions)
|
||||
- Consider adding filter capacitors on input pins for noisy environments
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_JOYSTICK_UP
|
||||
joystick = new Joystick(
|
||||
this, // owner
|
||||
PIN_JOYSTICK_UP, // pinUp
|
||||
PIN_JOYSTICK_DOWN, // pinDown
|
||||
PIN_JOYSTICK_LEFT, // pinLeft
|
||||
PIN_JOYSTICK_RIGHT, // pinRight
|
||||
JOYSTICK_MB_ADDR // modbusAddress
|
||||
);
|
||||
if (joystick) {
|
||||
components.push_back(joystick);
|
||||
Log.infoln(F("Joystick initialized. Pins - Up:%d Down:%d Left:%d Right:%d, MB:%d"),
|
||||
PIN_JOYSTICK_UP, PIN_JOYSTICK_DOWN,
|
||||
PIN_JOYSTICK_LEFT, PIN_JOYSTICK_RIGHT,
|
||||
JOYSTICK_MB_ADDR);
|
||||
} else {
|
||||
Log.errorln(F("Joystick initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
122
docs-c/components/LEDFeedback.md
Normal file
122
docs-c/components/LEDFeedback.md
Normal file
@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "LED Feedback Component Documentation"
|
||||
description: "Documentation for the LED Feedback component providing visual status indicators using addressable LED strips"
|
||||
keywords: "LED Feedback, NeoPixel, WS2812B, SK6812, ESP32, visual indicator"
|
||||
---
|
||||
|
||||
## LED Feedback
|
||||
|
||||
**Path**: [`src/LEDFeedback.cpp`](../src/LEDFeedback.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The LED Feedback component provides visual status indication through addressable LED strips (NeoPixel compatible). It offers multiple display modes including fading effects, level indicators, and tri-color blinking patterns that can be controlled via Modbus.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Digital output pin connected to WS2812B/SK6812 compatible LED strip
|
||||
- 5V power supply for the LED strip (separate from microcontroller logic)
|
||||
- Modbus TCP connection for remote control
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Multiple display modes:
|
||||
- OFF: All LEDs turned off
|
||||
- FADE_R_B: Smooth color transition between red and blue
|
||||
- RANGE: Level indicator (0-100%) using lit LEDs
|
||||
- TRI_COLOR_BLINK: Three-section traffic light style blinking (red, yellow, green)
|
||||
- Modbus control interface for mode selection and parameters
|
||||
- Adjustable update rate for animations
|
||||
- Configurable pixel count to support different strip lengths
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Adafruit_NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel) - Library for controlling addressable LED strips
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - Logging functionality
|
||||
- [ModbusTCP](../src/modbus/ModbusTCP.h) - For Modbus communication
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
LEDFeedback --> Component
|
||||
LEDFeedback --> Adafruit_NeoPixel
|
||||
LEDFeedback --> ModbusTCP
|
||||
LEDFeedback --> ArduinoLog
|
||||
LEDFeedback --> Bridge
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> OFF
|
||||
OFF --> FADE_R_B: Modbus write mode=1
|
||||
OFF --> RANGE: Modbus write mode=2
|
||||
OFF --> TRI_COLOR_BLINK: Modbus write mode=3
|
||||
|
||||
FADE_R_B --> OFF: Modbus write mode=0
|
||||
FADE_R_B --> RANGE: Modbus write mode=2
|
||||
FADE_R_B --> TRI_COLOR_BLINK: Modbus write mode=3
|
||||
|
||||
RANGE --> OFF: Modbus write mode=0
|
||||
RANGE --> FADE_R_B: Modbus write mode=1
|
||||
RANGE --> TRI_COLOR_BLINK: Modbus write mode=3
|
||||
RANGE: Update level via Modbus
|
||||
|
||||
TRI_COLOR_BLINK --> OFF: Modbus write mode=0
|
||||
TRI_COLOR_BLINK --> FADE_R_B: Modbus write mode=1
|
||||
TRI_COLOR_BLINK --> RANGE: Modbus write mode=2
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider power consumption optimization for battery-powered applications
|
||||
- Investigate using DMA-based LED control to reduce CPU usage
|
||||
- Add brightness control via Modbus to manage power usage
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Validate Modbus values more strictly to prevent unexpected behavior
|
||||
- Consider adding access control for mode changes
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Verify EMC compliance when LEDs change rapidly (potential for EMI)
|
||||
- Ensure ADA compliance for visual indicators in public/commercial settings
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use adequate power supply for LED strips (60mA per pixel at full brightness)
|
||||
- Consider adding a level-shifting circuit when connecting 3.3V microcontrollers to 5V LED strips
|
||||
- Add physical protection for LEDs in industrial environments
|
||||
- Implement custom modes for specific application requirements
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example shows how to initialize and mount an LED Feedback component in an application:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_LED_FEEDBACK_0
|
||||
ledFeedback_0 = new LEDFeedback(
|
||||
this, // owner
|
||||
PIN_LED_FEEDBACK_0, // pin
|
||||
LED_PIXEL_COUNT_0, // pixelCount
|
||||
ID_LED_FEEDBACK_0, // id
|
||||
LED_FEEDBACK_0_MB_ADDR // modbusAddress
|
||||
);
|
||||
if (ledFeedback_0)
|
||||
{
|
||||
components.push_back(ledFeedback_0);
|
||||
Log.infoln(F("LEDFeedback_0 initialized. Pin:%d, Count:%d, ID:%d, MB:%d"),
|
||||
PIN_LED_FEEDBACK_0, LED_PIXEL_COUNT_0,
|
||||
ID_LED_FEEDBACK_0, LED_FEEDBACK_0_MB_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("LEDFeedback_0 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
123
docs-c/components/ModbusLogicEngine.md
Normal file
123
docs-c/components/ModbusLogicEngine.md
Normal file
@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "Modbus Logic Engine"
|
||||
description: "A scriptable rule engine for industrial ESP-32 applications using Modbus"
|
||||
keywords: ["ESP-32", "Modbus", "Logic Engine", "Rule Engine", "Automation"]
|
||||
---
|
||||
|
||||
## Modbus Logic Engine
|
||||
|
||||
**Path**: [`src/ModbusLogicEngine.cpp`](../src/ModbusLogicEngine.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Modbus Logic Engine is a programmable rule engine that allows defining conditional logic rules through Modbus registers. It evaluates conditions on register values and executes actions when conditions are met, providing automation capabilities without requiring firmware modifications.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- ESP-32 microcontroller
|
||||
- Platform.io development environment
|
||||
- Modbus TCP/RTU implementation
|
||||
- Feature flag `ENABLE_MB_SCRIPT` must be defined in configuration
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Rules-based automation through Modbus registers
|
||||
- Configurable conditions with multiple comparison operators
|
||||
- Multiple action types including:
|
||||
- Writing to Modbus registers
|
||||
- Setting coils
|
||||
- Calling component methods
|
||||
- Debug flags for troubleshooting
|
||||
- Rule status monitoring and counters
|
||||
- Configurable evaluation interval
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Component.h](../src/Component.h) - Base component class
|
||||
- [ArduinoLog.h](../lib/ArduinoLog/ArduinoLog.h) - Logging functionality
|
||||
- [ModbusTypes.h](../src/modbus/ModbusTypes.h) - Modbus type definitions
|
||||
- [PHApp.h](../src/PHApp.h) - Application context
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
ModbusLogicEngine --> Component
|
||||
ModbusLogicEngine --> ModbusTypes
|
||||
ModbusLogicEngine --> PHApp
|
||||
ModbusLogicEngine --> ArduinoLog
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The Modbus Logic Engine continuously evaluates rules at a configurable interval, checking conditions against Modbus register values and executing actions when conditions are met.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialization
|
||||
Initialization --> Idle
|
||||
Idle --> EvaluateRules: Interval elapsed
|
||||
EvaluateRules --> CheckCondition
|
||||
CheckCondition --> PerformAction: Condition met
|
||||
CheckCondition --> Idle: Condition not met
|
||||
PerformAction --> Idle
|
||||
EvaluateRules --> Idle: All rules processed
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider adding a priority system for rules that need faster evaluation
|
||||
- Optimize condition evaluation by caching register values when multiple rules reference the same address
|
||||
- Implement batch processing for rules that write to sequential registers
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Consider adding authentication for modifying rule configurations
|
||||
- Implement range checking for target addresses to prevent unauthorized access
|
||||
- Add validation for rule parameters to prevent malformed rules
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure rule execution timing meets industrial control requirements
|
||||
- Document rule format for compliance with automation standards
|
||||
- Implement logging capabilities for audit trails in regulated environments
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use separate register blocks for different rule sets to improve organization
|
||||
- Implement a backup/restore mechanism for rule configurations
|
||||
- Consider a graphical rule editor for easier configuration
|
||||
- Add rule dependencies to allow chaining of rules
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
The Modbus Logic Engine is typically constructed early in the application startup:
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_MB_SCRIPT
|
||||
modbusLogicEngine = new ModbusLogicEngine(
|
||||
this // Owner (PHApp instance)
|
||||
);
|
||||
if (modbusLogicEngine) {
|
||||
components.push_back(modbusLogicEngine);
|
||||
Log.infoln(F("ModbusLogicEngine initialized."));
|
||||
|
||||
// Register component methods that can be called from rules
|
||||
modbusLogicEngine->registerMethod(
|
||||
COMPONENT_ID_LED, // Component ID
|
||||
1, // Method ID
|
||||
[this](short arg1, short arg2) -> short {
|
||||
// Example method implementation
|
||||
if (ledComponent) {
|
||||
return ledComponent->setPattern(arg1);
|
||||
}
|
||||
return E_COMPONENT_ERROR;
|
||||
}
|
||||
);
|
||||
} else {
|
||||
Log.errorln(F("ModbusLogicEngine initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
137
docs-c/components/OmronE5.md
Normal file
137
docs-c/components/OmronE5.md
Normal file
@ -0,0 +1,137 @@
|
||||
---
|
||||
title: "OmronE5 - Temperature Controller Component"
|
||||
description: "Interface for Omron E5 series temperature controllers via Modbus RTU"
|
||||
keywords: "omron, e5, temperature controller, modbus, rs485, industrial automation"
|
||||
---
|
||||
|
||||
## OmronE5
|
||||
|
||||
**Path**: [`./src/components/OmronE5.cpp`](./src/components/OmronE5.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The OmronE5 component provides an interface to Omron E5 series temperature controllers via Modbus-RTU over RS485. It enables temperature monitoring, setpoint control, and advanced heat rate analytics for industrial control applications.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Hardware:
|
||||
- RS485 transceiver module connected to ESP32
|
||||
- Properly configured Omron E5 controller with Modbus RTU capabilities
|
||||
- Software:
|
||||
- `ENABLE_RS485` must be defined in the configuration
|
||||
- Optional `ENABLE_TRUTH_COLLECTOR` for advanced statistical analysis
|
||||
- Optional `ENABLE_COOLING` for cooling mode support
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Read Process Value (PV) and Setpoint (SP) from the controller
|
||||
- Control the temperature setpoint
|
||||
- Monitor controller running/heating/cooling status
|
||||
- Start and stop the temperature controller
|
||||
- Advanced statistics (with TRUTH_COLLECTOR enabled):
|
||||
- Track mean error between PV and SP
|
||||
- Calculate heat rate (oscillations per minute)
|
||||
- Monitor power consumption (Wh)
|
||||
- Calculate PV/SP response lag
|
||||
- Track longest heating duration in time windows
|
||||
- Estimate energy costs
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - Logging functionality
|
||||
- [Component](./src/Component.h) - Base component system
|
||||
- [ModbusRTU](./src/modbus/ModbusRTU.h) - Modbus RTU communication
|
||||
- [ModbusTypes](./src/modbus/ModbusTypes.h) - Modbus data types
|
||||
- [OmronE5Types](./src/components/OmronE5Types.h) - Omron E5 specific constants
|
||||
- [xstatistics](./src/xstatistics.h) - Statistical calculations (when TRUTH_COLLECTOR enabled)
|
||||
- [ValueWrapper](./src/ValueWrapper.h) - Value change tracking
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
OmronE5 --> RTU_Base
|
||||
RTU_Base --> Component
|
||||
OmronE5 --> OmronE5Types
|
||||
OmronE5 --> ModbusTypes
|
||||
OmronE5 --> ValueWrapper
|
||||
OmronE5 --> xstatistics
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The component operates through read/write operations to specific Modbus registers on the Omron controller, with additional statistical analysis when enabled.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Setup
|
||||
Setup --> Running
|
||||
Running --> Reading: Every _readInterval ms
|
||||
Reading --> ProcessData: onRegisterUpdate
|
||||
ProcessData --> UpdateStats: When TRUTH_COLLECTOR enabled
|
||||
ProcessData --> CheckHeatUpState
|
||||
UpdateStats --> Running
|
||||
CheckHeatUpState --> Running
|
||||
Running --> HandleCommands: When command received
|
||||
HandleCommands --> SetSP
|
||||
HandleCommands --> RunStop
|
||||
HandleCommands --> Info
|
||||
HandleCommands --> ResetStats: When TRUTH_COLLECTOR enabled
|
||||
SetSP --> Running
|
||||
RunStop --> Running
|
||||
Info --> Running
|
||||
ResetStats --> Running
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider optimizing the read interval based on controller activity
|
||||
- Reduce read frequency during stable operations to minimize bus traffic
|
||||
- Group register reads where possible to minimize transaction overhead
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add range validation for all incoming Modbus values
|
||||
- Implement authentication for control operations if needed in sensitive installations
|
||||
- Consider adding checksums for critical value modifications
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure component behavior complies with relevant industrial control standards
|
||||
- Verify compatibility with different firmware versions of Omron E5 controllers
|
||||
- Document any deviations from standard Modbus implementations
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Configure the Omron E5 controller with compatible Modbus RTU settings (baud rate, parity)
|
||||
- Set appropriate register access permissions on the controller
|
||||
- Use the TRUTH_COLLECTOR feature for diagnostics and optimization
|
||||
- When using cooling functionality, ensure the controller is properly configured for heat/cool control
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
The following example demonstrates how to initialize an OmronE5 component within a parent component:
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_RS485
|
||||
// Create Omron E5 device with slave ID 1
|
||||
OmronE5* temperatureController = new OmronE5(
|
||||
this, // owner component
|
||||
1, // Modbus slave ID
|
||||
300 // read interval in ms
|
||||
);
|
||||
|
||||
if (temperatureController)
|
||||
{
|
||||
components.push_back(temperatureController);
|
||||
Log.infoln(F("OmronE5 temperature controller initialized. SlaveID:%d, ReadInterval:%d"),
|
||||
1, 300);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("OmronE5 temperature controller initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
105
docs-c/components/OmronE5Types.md
Normal file
105
docs-c/components/OmronE5Types.md
Normal file
@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Omron E5 Thermometer Types and Registers
|
||||
description: Documentation for the Omron E5 thermometer protocol implementation, including status codes, register addresses, and command definitions
|
||||
keywords: Omron, E5, Modbus, thermal controller, industrial, ESP32, PlatformIO
|
||||
---
|
||||
|
||||
## Omron E5 Types
|
||||
|
||||
**Path**: [`src/omron_e5_types.h`](../../src/omron_e5_types.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
This component provides type definitions, register maps, and command codes for interfacing with Omron E5 series thermal controllers via Modbus protocol. It defines all necessary constants, status bit positions, and register addresses to read sensor data and control the Omron E5 device.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Requires an RS-485 hardware interface (for Modbus RTU communication)
|
||||
- Properly connected Omron E5 series temperature controller
|
||||
- Compatible Modbus implementation in the codebase
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Complete register map for Omron E5 series controllers
|
||||
- Status bit position definitions for both status words
|
||||
- Predefined commands for device control operations
|
||||
- Error code definitions for diagnostics
|
||||
- Useful macros for bit manipulation and command creation
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Modbus implementation](../../src/modbus.h)
|
||||
- [Logger](../../src/logger.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
OmronE5 --> Modbus
|
||||
OmronE5 --> Logger
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The component provides definitions that enable the main application to interact with Omron E5 temperature controllers.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Application->>OmronE5: Request status/temperature
|
||||
OmronE5->>Modbus: Format Modbus request
|
||||
Modbus->>E5Device: Send command via RS-485
|
||||
E5Device->>Modbus: Send response
|
||||
Modbus->>OmronE5: Process response
|
||||
OmronE5->>Application: Return decoded data
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider adding caching mechanisms for frequently accessed values
|
||||
- Implement batch read operations to reduce communication overhead
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add input validation for all commands sent to the device
|
||||
- Implement error recovery mechanisms
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with industrial automation standards
|
||||
- Verify register map against latest Omron E5 documentation
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Create higher-level functions that abstract common operations (e.g., reading temperature, setting limits)
|
||||
- Add temperature unit conversion utilities
|
||||
- Consider implementing automatic reconnection on communication failures
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef HAS_OMRON_E5
|
||||
omronE5Controller = new OmronE5Controller(
|
||||
this, // owner
|
||||
&rs485, // modbus interface
|
||||
OMRON_E5_DEVICE_ID, // modbus device id
|
||||
OMRON_E5_MB_ADDR // modbus address
|
||||
);
|
||||
|
||||
if (omronE5Controller) {
|
||||
components.push_back(omronE5Controller);
|
||||
Log.infoln(F("OmronE5Controller initialized. Device ID: %d, MB Address: %d"),
|
||||
OMRON_E5_DEVICE_ID, OMRON_E5_MB_ADDR);
|
||||
|
||||
// Configure initial settings
|
||||
omronE5Controller->setTargetTemperature(DEFAULT_TARGET_TEMP);
|
||||
omronE5Controller->setAlarmLimits(MIN_TEMP_ALARM, MAX_TEMP_ALARM);
|
||||
omronE5Controller->startOperation();
|
||||
} else {
|
||||
Log.errorln(F("OmronE5Controller initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
The Omron E5 implementation is based on the Omron E5 Communications Manual (h175_e5_c_communications_manual_en.pdf). The component provides extensive definitions for all status bits, alarm types, and register addresses as defined in the manual sections 3-24, 3-25, and 5-1 through 5-2.
|
||||
123
docs-c/components/OmronE5_Ex.md
Normal file
123
docs-c/components/OmronE5_Ex.md
Normal file
@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "OMRONE5_EX Component Documentation"
|
||||
description: "Documentation for the OMRONE5_EX component used for communication with Omron E5 temperature controllers"
|
||||
keywords: "OMRONE5_EX, Omron, E5, temperature controller, Modbus, RTU, industrial control"
|
||||
---
|
||||
|
||||
## OMRONE5_EX
|
||||
|
||||
**Path**: [`src/omrone5_ex.h`](../../src/omrone5_ex.h)
|
||||
|
||||
**Revision History**:
|
||||
- Initial documentation
|
||||
|
||||
OMRONE5_EX is a component that provides a comprehensive interface for communication with Omron E5 series temperature controllers via Modbus RTU protocol. It includes an extensive mapping of the E5 controller's Modbus register addresses for temperature monitoring, control settings, alarm management, and device configuration.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- ESP-32 with RS-485 interface for Modbus RTU communication
|
||||
- Omron E5 series temperature controller
|
||||
- RS-485 wiring between ESP-32 and the controller
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Complete mapping of Omron E5 temperature controller Modbus registers
|
||||
- Support for PV (Process Value) temperature monitoring
|
||||
- Access to controller status and settings
|
||||
- Management of control parameters (PID settings, set points)
|
||||
- Alarm configuration and monitoring
|
||||
- Support for various temperature input types and scaling
|
||||
- Communication and display settings control
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ModbusClient](../../src/modbus_client.h)
|
||||
- [Logger](../../src/logger.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
OMRONE5_EX --> ModbusClient
|
||||
OMRONE5_EX --> Logger
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The component primarily serves as a register map for Modbus communication with Omron E5 controllers:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialize
|
||||
Initialize --> Ready
|
||||
Ready --> ReadRegisters: Read temperature
|
||||
Ready --> WriteRegisters: Change settings
|
||||
ReadRegisters --> Ready: Return data
|
||||
WriteRegisters --> Ready: Settings updated
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing register caching to reduce communication overhead
|
||||
- Optimize reading of frequently used registers with multi-register read operations
|
||||
- Implement error recovery mechanisms for communication failures
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add validation of values before writing to controller registers
|
||||
- Implement authentication for critical setting changes
|
||||
- Consider encryption for sensitive parameter transmission
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with industrial control standards (IEC 61131)
|
||||
- Validate operation against Omron E5 series specifications
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Create specialized methods for common operations (e.g., reading temperature, changing set points)
|
||||
- Implement a health monitoring system to detect controller disconnections
|
||||
- Add automatic reconnection capabilities after communication failures
|
||||
- Document temperature scaling factors for different sensor types
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
// Create an instance of the OMRONE5_EX component with Modbus connection
|
||||
#ifdef USE_OMRON_E5_CONTROLLER
|
||||
omronE5Controller = new OMRONE5_EX(
|
||||
this, // owner
|
||||
&modbusClient, // modbus client
|
||||
OMRON_E5_UNIT_ID, // Modbus unit ID for the controller
|
||||
OMRON_E5_UPDATE_RATE // Update rate in milliseconds
|
||||
);
|
||||
|
||||
if (omronE5Controller) {
|
||||
components.push_back(omronE5Controller);
|
||||
Log.infoln(F("OMRONE5_EX initialized. Unit ID: %d, Update rate: %d ms"),
|
||||
OMRON_E5_UNIT_ID, OMRON_E5_UPDATE_RATE);
|
||||
|
||||
// Configure controller with initial settings
|
||||
omronE5Controller->writeRegister(
|
||||
static_cast<uint16_t>(ModbusAddresses::OR_E5_SWR_SET_POINT),
|
||||
initialSetPoint
|
||||
);
|
||||
} else {
|
||||
Log.errorln(F("OMRONE5_EX initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
The OMRONE5_EX component provides an extensive Modbus address map for the Omron E5 series temperature controllers, including addresses for:
|
||||
- Temperature monitoring (PV)
|
||||
- Controller status
|
||||
- Set points and control parameters
|
||||
- PID tuning parameters
|
||||
- Alarm configuration
|
||||
- Input and output settings
|
||||
- Display configuration
|
||||
- Communication parameters
|
||||
|
||||
For detailed information on each register's purpose and valid values, refer to the Omron E5 Series User Manual.
|
||||
147
docs-c/components/POT.md
Normal file
147
docs-c/components/POT.md
Normal file
@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "POT - Analog Potentiometer Reader Component"
|
||||
description: "ESP32 analog potentiometer reader with digital filtering capabilities and Modbus integration"
|
||||
keywords: ["ESP32", "potentiometer", "analog", "filtering", "modbus", "industrial control", "embedded systems"]
|
||||
---
|
||||
|
||||
## POT - Analog Potentiometer Reader
|
||||
|
||||
**Path**: [`src/pot.h`](../../../src/pot.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
A lightweight, efficient analog potentiometer reader component with multiple filtering options and Modbus integration. It features three damping algorithms (none, moving average, and EMA), deadband processing to suppress noise, and support for both local and remote control modes.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- **Hardware**:
|
||||
- Analog input pin for potentiometer connection
|
||||
- Optional RC low-pass filter hardware for additional noise reduction
|
||||
- **Software**:
|
||||
- Arduino framework
|
||||
- ArduinoLog library
|
||||
- Modbus support (ModbusTCP)
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Three damping algorithms:
|
||||
- No damping (raw readings)
|
||||
- Moving Average (box-car) filtering with configurable window size
|
||||
- Exponential Moving Average (EMA) with configurable alpha
|
||||
- Dead-band filtering to suppress small value changes
|
||||
- Configurable scaling from raw ADC values (0-1023) to application range (0-100 by default)
|
||||
- Modbus TCP integration with support for:
|
||||
- Reading current potentiometer value
|
||||
- Switching between local and remote control modes
|
||||
- Setting remote value for when in remote control mode
|
||||
- No dynamic memory allocation, designed for resource-constrained microcontrollers
|
||||
- Avoids floating-point operations for optimal performance
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Component](../../../src/Component.h)
|
||||
- [App](../../../src/App.h)
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
||||
- [Modbus](../../../src/modbus/Modbus.h)
|
||||
- [ModbusTCP](../../../src/modbus/ModbusTCP.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
POT --> Component
|
||||
POT --> App
|
||||
POT --> ArduinoLog
|
||||
POT --> Modbus
|
||||
POT --> ModbusTCP
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Setup: Initialization
|
||||
Setup --> Local: Default Mode
|
||||
Setup --> Remote: Via Modbus
|
||||
|
||||
state Local {
|
||||
[*] --> ReadAnalogValue
|
||||
ReadAnalogValue --> ApplyFilter
|
||||
ApplyFilter --> ApplyDeadband
|
||||
ApplyDeadband --> NotifyIfChanged
|
||||
}
|
||||
|
||||
state Remote {
|
||||
[*] --> ReadModbusValue
|
||||
ReadModbusValue --> NotifyIfChanged
|
||||
}
|
||||
|
||||
Local --> Remote: Mode Change via Modbus
|
||||
Remote --> Local: Mode Change via Modbus
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider adaptive filtering based on rate of change for better response characteristics
|
||||
- Explore efficient normalization techniques to handle different ADC resolutions (10-bit vs 12-bit)
|
||||
- Implement more sophisticated filtering algorithms if needed for high-noise environments
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add bounds checking for remote control values to prevent overflow/underflow conditions
|
||||
- Implement authentication for remote control mode changes in security-sensitive applications
|
||||
- Consider adding fail-safe behavior for loss of Modbus communication
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Verify compliance with IEC 61131-3 for industrial control systems
|
||||
- Ensure Modbus implementation follows Modbus specification guidelines
|
||||
- Document EMC considerations for analog input circuits
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use a hardware RC low-pass filter as suggested in the component comments for noisy environments
|
||||
- Select appropriate damping algorithm based on application needs:
|
||||
- NONE: Fast response but noisy
|
||||
- MOVING_AVERAGE: Good balance of smoothing and responsiveness
|
||||
- EMA: Smooth response with less memory requirements
|
||||
- Adjust deadband (POT_DEADBAND) based on the stability requirements of the application
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example demonstrates how to initialize a POT component with moving average filtering:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_POT_SPEED
|
||||
potSpeed = new POT(
|
||||
this, // owner
|
||||
PIN_POT_SPEED, // pin
|
||||
ID_POT_SPEED, // id
|
||||
POT_SPEED_MB_ADDR, // modbusAddress
|
||||
POTDampingAlgorithm::DAMPING_MOVING_AVERAGE // filtering algorithm
|
||||
);
|
||||
|
||||
if (potSpeed)
|
||||
{
|
||||
components.push_back(potSpeed);
|
||||
Log.infoln(F("POT Speed initialized. Pin:%d, ID:%d, MB:%d"),
|
||||
PIN_POT_SPEED, ID_POT_SPEED, POT_SPEED_MB_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("POT Speed initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
The component implements several filtering techniques for noise reduction:
|
||||
|
||||
- **Moving Average**: Implemented as an incremental ring buffer with O(1) complexity
|
||||
- **Exponential Moving Average (EMA)**: Uses a 1-pole IIR filter with the formula: `y[n] = y[n-1] + (x[n] - y[n-1]) / 2^k`
|
||||
|
||||
The hardware recommendations include an RC low-pass filter with the potentiometer itself serving as the resistor, and suggested capacitor values based on desired cutoff frequencies:
|
||||
- For faster response (~30 Hz): Use 1 μF
|
||||
- For moderate filtering (~10 Hz): Use 2.2 μF or 3.3 μF
|
||||
- For more smoothing (~5 Hz): Use 4.7 μF or 6.8 μF
|
||||
206
docs-c/components/Plunger.md
Normal file
206
docs-c/components/Plunger.md
Normal file
@ -0,0 +1,206 @@
|
||||
---
|
||||
title: "Plunger Component Documentation"
|
||||
description: "Documentation for the Plunger component in an ESP-32 industrial device with Modbus-485 capability"
|
||||
keywords: ["ESP-32", "Plunger", "VFD", "Modbus", "industrial", "PlatformIO"]
|
||||
---
|
||||
|
||||
# Plunger
|
||||
|
||||
**Path**: [`src/Plunger.cpp`](../src/Plunger.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Plunger component controls a motor-driven plunger mechanism through a Variable Frequency Drive (VFD). It manages various states including homing, plunging, filling operations, and post-flow sequences while allowing both manual and automatic operation modes.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Hardware
|
||||
- VFD-controlled motor connected to plunger mechanism
|
||||
- Joystick peripheral for manual control
|
||||
- Modbus-485 communication interface
|
||||
|
||||
### Configuration
|
||||
- Multiple configurable speed settings
|
||||
- Operation timing parameters
|
||||
- Auto mode hold durations
|
||||
|
||||
## Features
|
||||
|
||||
- Multiple operation modes:
|
||||
- Manual control via joystick
|
||||
- Auto mode via joystick hold
|
||||
- Replay of recorded plunge sequences
|
||||
- Filling sequence with configurable parameters
|
||||
- Post-flow sequence for pressure maintenance
|
||||
- State machine design with comprehensive state transitions
|
||||
- Jam detection and recovery
|
||||
- Modbus control interface
|
||||
- Configurable timings and speeds
|
||||
- Recording and replaying of plunge operations
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [Arduino Framework](https://www.arduino.cc/)
|
||||
- [VFD Component](../src/VFD.cpp)
|
||||
- [Joystick Component](../src/Joystick.cpp)
|
||||
- [Ticker Library](https://github.com/esp8266/Arduino/tree/master/libraries/Ticker)
|
||||
- [ModbusTCP](../src/ModbusTCP.cpp)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Plunger --> VFD
|
||||
Plunger --> Joystick
|
||||
Plunger --> Ticker
|
||||
Plunger --> ModbusTCP
|
||||
Plunger --> Arduino
|
||||
```
|
||||
|
||||
## Behavior
|
||||
|
||||
The Plunger component operates as a state machine with the following states:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> IDLE
|
||||
|
||||
IDLE --> HOMING_MANUAL: Joystick UP
|
||||
IDLE --> PLUNGING_MANUAL: Joystick DOWN
|
||||
IDLE --> FILLING: Joystick LEFT + HOLD
|
||||
IDLE --> RECORD: Joystick RIGHT + HOLD
|
||||
IDLE --> REPLAY: Joystick RIGHT + BRIEF
|
||||
|
||||
HOMING_MANUAL --> HOMING_AUTO: HOLD > autoModeHoldDuration
|
||||
HOMING_MANUAL --> STOPPING: Joystick release
|
||||
|
||||
PLUNGING_MANUAL --> PLUNGING_AUTO: HOLD > autoModeHoldDuration
|
||||
PLUNGING_MANUAL --> STOPPING: Joystick release
|
||||
|
||||
HOMING_AUTO --> STOPPING: Joystick non-center after release
|
||||
PLUNGING_AUTO --> STOPPING: Joystick non-center after release
|
||||
|
||||
RECORD --> IDLE: Joystick non-RIGHT
|
||||
|
||||
REPLAY --> STOPPING: Joystick non-CENTER
|
||||
REPLAY --> POST_FLOW: Plunge completed, post-flow enabled
|
||||
REPLAY --> IDLE: Plunge completed, post-flow disabled
|
||||
|
||||
FILLING --> STOPPING: Joystick non-CENTER after release
|
||||
|
||||
JAMMED --> RESETTING_JAM
|
||||
RESETTING_JAM --> HOMING_MANUAL: Joystick UP
|
||||
RESETTING_JAM --> IDLE: Joystick non-UP/non-CENTER
|
||||
|
||||
POST_FLOW --> STOPPING: Joystick non-CENTER after release
|
||||
POST_FLOW --> IDLE: Post-flow completed
|
||||
|
||||
STOPPING --> IDLE
|
||||
|
||||
state FILLING {
|
||||
[*] --> PLUNGING
|
||||
PLUNGING --> PLUNGED: Plunge completed
|
||||
PLUNGED --> HOMING: Plunged wait timeout
|
||||
HOMING --> HOMED: Home completed
|
||||
HOMED --> [*]: Homed wait timeout
|
||||
}
|
||||
|
||||
state POST_FLOW {
|
||||
[*] --> POST_FLOW_STOPPING
|
||||
POST_FLOW_STOPPING --> POST_FLOW_STARTING: Stopping wait timeout
|
||||
POST_FLOW_STARTING --> POST_FLOW_COMPLETE: Duration timeout
|
||||
POST_FLOW_COMPLETE --> [*]: Complete wait timeout
|
||||
}
|
||||
|
||||
note right of IDLE: Default state waiting for input
|
||||
note right of JAMMED: Detected overcurrent condition
|
||||
note right of STOPPING: Transitional state to IDLE
|
||||
```
|
||||
|
||||
## TODOs
|
||||
|
||||
### Performance
|
||||
|
||||
- Consider optimizing timer usage to reduce RAM footprint
|
||||
- Evaluate performance impact of multiple state transitions during operation
|
||||
- Implement configurable acceleration/deceleration profiles for smoother operation
|
||||
- Assess VFD command frequency to prevent communication bottlenecks
|
||||
|
||||
### Security
|
||||
|
||||
- Implement validation of Modbus command sources
|
||||
- Add access control to prevent unauthorized command execution
|
||||
- Consider adding confirmation requirements for critical operations
|
||||
- Log and alert on suspicious command patterns
|
||||
|
||||
### Compliance
|
||||
|
||||
- Ensure compliance with relevant machine safety standards
|
||||
- Consider implementing additional safety interlocks
|
||||
- Document safety requirements and certifications
|
||||
- Follow applicable electrical code requirements for industrial equipment
|
||||
|
||||
### Recommendations
|
||||
|
||||
- Monitor VFD current to detect potential mechanical issues before jam events
|
||||
- Implement a maintenance log for plunger operations
|
||||
- Consider adding physical position sensing for more precise control
|
||||
- Develop UX guidelines for joystick operation to minimize user error
|
||||
- Create a calibration routine for optimal performance with different materials
|
||||
|
||||
## Example
|
||||
|
||||
The following example shows how to initialize and mount a Plunger component:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_PLUNGER_1_ENABLE
|
||||
vfd_1 = new VFD(
|
||||
this, // owner
|
||||
PIN_PLUNGER_1_ENABLE, // enablePin
|
||||
PIN_PLUNGER_1_FORWARD, // forwardPin
|
||||
PIN_PLUNGER_1_COM, // communicationPin
|
||||
PIN_PLUNGER_1_ALARM, // alarmPin
|
||||
PLUNGER_1_ID_VFD // id
|
||||
);
|
||||
|
||||
joystick_1 = new Joystick(
|
||||
this, // owner
|
||||
PIN_PLUNGER_1_JOYSTICK_X, // pinX
|
||||
PIN_PLUNGER_1_JOYSTICK_Y, // pinY
|
||||
PLUNGER_1_ID_JOYSTICK // id
|
||||
);
|
||||
|
||||
if (vfd_1 && joystick_1)
|
||||
{
|
||||
plunger_1 = new Plunger(
|
||||
this, // owner
|
||||
vfd_1, // vfd
|
||||
joystick_1, // joystick
|
||||
PLUNGER_1_ID // id
|
||||
);
|
||||
|
||||
// Configure plunger settings
|
||||
plunger_1->settings.speedRampHz = PLUNGER_1_SPEED_RAMP_HZ;
|
||||
plunger_1->settings.speedSlowHz = PLUNGER_1_SPEED_SLOW_HZ;
|
||||
plunger_1->settings.speedMaxHz = PLUNGER_1_SPEED_MAX_HZ;
|
||||
plunger_1->settings.autoModeHoldDurationMs = PLUNGER_1_AUTO_MODE_HOLD_DURATION_MS;
|
||||
plunger_1->settings.defaultMaxOperationDurationMs = PLUNGER_1_MAX_OPERATION_DURATION_MS;
|
||||
plunger_1->settings.enablePostFlow = PLUNGER_1_ENABLE_POST_FLOW;
|
||||
|
||||
// Add to components list
|
||||
if (plunger_1) {
|
||||
components.push_back(vfd_1);
|
||||
components.push_back(joystick_1);
|
||||
components.push_back(plunger_1);
|
||||
|
||||
Log.infoln(F("Plunger_1 initialized with VFD and Joystick"));
|
||||
}
|
||||
else {
|
||||
Log.errorln(F("Plunger_1 initialization failed."));
|
||||
}
|
||||
}
|
||||
else {
|
||||
Log.errorln(F("VFD_1 or Joystick_1 initialization failed, cannot create Plunger_1."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
133
docs-c/components/PlungerSettings.md
Normal file
133
docs-c/components/PlungerSettings.md
Normal file
@ -0,0 +1,133 @@
|
||||
---
|
||||
title: "Plunger Settings Component"
|
||||
description: "Configuration management for plunger mechanism parameters with persistence capabilities"
|
||||
keywords: ["plunger", "settings", "configuration", "ESP32", "json", "persistence"]
|
||||
---
|
||||
|
||||
## PlungerSettings
|
||||
|
||||
**Path**: [src/PlungerSettings.h](../src/PlungerSettings.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
PlungerSettings is a configuration management component for plunger mechanisms. It provides a structured way to define, store, and retrieve operational parameters for plunger controls, including speeds, timeouts, current thresholds, and behavioral settings. The component supports JSON serialization for persistent storage in the filesystem.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- LittleFS filesystem support for persistent storage
|
||||
- JSON processing capabilities (via ArduinoJson)
|
||||
- Logging functionality (ArduinoLog)
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Comprehensive parameter set for plunger operation control
|
||||
- Default values based on predefined constants
|
||||
- JSON serialization and deserialization
|
||||
- Persistent storage in LittleFS
|
||||
- Type-safe parameter parsing with error handling
|
||||
- Detailed diagnostic logging
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Arduino.h](https://github.com/espressif/arduino-esp32)
|
||||
- [ArduinoJson](https://arduinojson.org/)
|
||||
- [LittleFS](https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html)
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
||||
- [Plunger.h](../src/Plunger.h) (for default constants)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
PlungerSettings --> Arduino
|
||||
PlungerSettings --> ArduinoJson
|
||||
PlungerSettings --> LittleFS
|
||||
PlungerSettings --> ArduinoLog
|
||||
PlungerSettings --> Plunger
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Constructor] --> B{Default Values}
|
||||
B -->|From Constants| C[Initialize Settings]
|
||||
B -->|From Parameters| D[Initialize Settings]
|
||||
|
||||
E[Load Settings] --> F{File Exists?}
|
||||
F -->|Yes| G[Parse JSON]
|
||||
F -->|No| H[Keep Default Values]
|
||||
G --> I{Parse Success?}
|
||||
I -->|Yes| J[Update Settings]
|
||||
I -->|No| K[Keep Default Values]
|
||||
|
||||
L[Save Settings] --> M[Serialize to JSON]
|
||||
M --> N[Write to File]
|
||||
|
||||
O[fromJson] --> P[Parse Each Setting]
|
||||
P --> Q[Type Validation]
|
||||
Q -->|Valid| R[Update Setting]
|
||||
Q -->|Invalid| S[Keep Default Value]
|
||||
|
||||
T[print] --> U[Log All Settings]
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider using a static JsonDocument with predefined capacity to avoid dynamic memory allocation
|
||||
- Implement selective parameter updates to minimize file writes
|
||||
- Add validation ranges for settings to prevent extreme values that might cause hardware issues
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Consider adding checksums or signatures to detect tampering with settings files
|
||||
- Implement access control mechanisms for settings modification
|
||||
- Sanitize inputs from external sources before applying to settings
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure parameter ranges comply with hardware specifications
|
||||
- Add parameter validation to prevent unsafe mechanical operations
|
||||
- Document any safety-critical parameters and their implications
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Create a web-based configuration interface for easy parameter adjustment
|
||||
- Implement settings profiles for different operational scenarios
|
||||
- Add ability to backup/restore settings to/from external storage
|
||||
- Consider implementing periodic settings validation to detect drift or corruption
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
The PlungerSettings component can be used as follows:
|
||||
|
||||
```cpp
|
||||
// Create settings object with default values
|
||||
PlungerSettings settings;
|
||||
|
||||
// Load saved settings from filesystem
|
||||
if (settings.load()) {
|
||||
Log.infoln("Loaded plunger settings from filesystem");
|
||||
} else {
|
||||
Log.warningln("Using default plunger settings");
|
||||
|
||||
// Save current defaults to create the settings file
|
||||
settings.save();
|
||||
}
|
||||
|
||||
// Access settings
|
||||
uint16_t speed = settings.speedMediumHz;
|
||||
|
||||
// Update a setting
|
||||
settings.currentJamThresholdMa = 1200;
|
||||
|
||||
// Save updated settings
|
||||
settings.save();
|
||||
|
||||
// Debug output all settings
|
||||
settings.print();
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
Documentation for the PlungerSettings class including JSON serialization and deserialization methods, persistent storage capabilities, and configuration parameters for plunger operation control.
|
||||
122
docs-c/components/RS485.md
Normal file
122
docs-c/components/RS485.md
Normal file
@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "RS485 Component - Modbus RTU Interface"
|
||||
description: "RS485 component provides a Modbus RTU interface for industrial applications"
|
||||
keywords: ["ESP32", "RS485", "Modbus", "RTU", "industrial", "interface", "communication"]
|
||||
---
|
||||
|
||||
## RS485
|
||||
|
||||
**Path**: [src/RS485.cpp](src/RS485.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The RS485 component provides a Modbus RTU interface for industrial communications. It acts as a gateway between Modbus TCP and Modbus RTU, managing serial communications with connected hardware devices and exposing them to the higher-level systems.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Hardware:
|
||||
- RS485 transceiver (typically connected to a UART port)
|
||||
- GPIO pin for DE/RE (Data Enable/Receive Enable) control
|
||||
- UART pins (RXD1_PIN, TXD1_PIN)
|
||||
- Software:
|
||||
- ModbusClientRTU library
|
||||
- ModbusRTU implementation
|
||||
- Configuration in config-modbus.h
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Manages communication with multiple Modbus RTU slave devices
|
||||
- Bridges between Modbus TCP and Modbus RTU protocols
|
||||
- Monitors and reports register changes from devices
|
||||
- Provides error handling and reporting
|
||||
- Supports device discovery and monitoring
|
||||
- Dynamic registration of device capabilities with TCP server
|
||||
- Periodic polling of RTU devices
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Component](src/Component.h) - Base component system
|
||||
- [ModbusRTU](src/modbus/ModbusRTU.h) - Modbus RTU implementation
|
||||
- [ModbusTypes](src/modbus/ModbusTypes.h) - Common Modbus data types
|
||||
- [RTUutils](src/RTUutils.h) - Utilities for RTU communication
|
||||
- [RS485Devices](src/RS485Devices.h) - Device registration
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
RS485 --> Component
|
||||
RS485 --> ModbusRTU
|
||||
RS485 --> ModbusTypes
|
||||
RS485 --> RTUutils
|
||||
RS485 --> RS485Devices
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialize
|
||||
Initialize --> Running: Setup successful
|
||||
Initialize --> Error: Setup failed
|
||||
|
||||
Running --> ProcessLoop: RS485_LOOP_INTERVAL_MS
|
||||
ProcessLoop --> HandleRegisterChange: On device register change
|
||||
ProcessLoop --> HandleDeviceStatus: Device status updated
|
||||
ProcessLoop --> Running: Return to main loop
|
||||
|
||||
HandleRegisterChange --> ForwardToTCP: Notify TCP interface
|
||||
HandleRegisterChange --> Running
|
||||
|
||||
Error --> [*]
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider optimizing polling frequency based on device importance or activity
|
||||
- Implement batched read operations for devices with consecutive register addresses
|
||||
- Add performance metrics tracking for RS485 bus utilization and response times
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement validation of received data to prevent buffer overflows
|
||||
- Add authentication mechanisms for critical device communications
|
||||
- Consider encryption for sensitive data transmission
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure full compliance with Modbus RTU specification
|
||||
- Consider implementing Modbus exceptions handling according to standard
|
||||
- Document protocol compatibility with various industrial equipment standards
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Create a configuration tool to easily manage device mappings
|
||||
- Implement automatic baudrate detection for connected devices
|
||||
- Add diagnostic features for bus monitoring and troubleshooting
|
||||
- Consider implementing a fallback mechanism for unreliable connections
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example shows how to initialize and mount the RS485 component in a main application:
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_RS485
|
||||
rs485 = new RS485(this); // 'this' is the owner component
|
||||
if (rs485) {
|
||||
components.push_back(rs485);
|
||||
Log.infoln(F("RS485 component initialized."));
|
||||
|
||||
// Register RS485 as ModbusTCP data provider, if TCP is available
|
||||
#ifdef ENABLE_MODBUS_TCP
|
||||
if (modbusTCP) {
|
||||
rs485->mb_tcp_register(modbusTCP);
|
||||
}
|
||||
#endif
|
||||
} else {
|
||||
Log.errorln(F("RS485 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
109
docs-c/components/Relay.md
Normal file
109
docs-c/components/Relay.md
Normal file
@ -0,0 +1,109 @@
|
||||
---
|
||||
title: "Relay Component Documentation"
|
||||
description: "Documentation for the Relay component which provides control of digital relays with Modbus integration"
|
||||
keywords: [relay, modbus, component, switch, control, esp32]
|
||||
---
|
||||
|
||||
## Relay
|
||||
|
||||
**Path**: [`src/Relay.h`](../../src/Relay.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The Relay component provides a simple interface for controlling digital relay outputs with Modbus integration. It enables turning physical relays on and off both programmatically and via Modbus commands, making it suitable for industrial control applications with remote management capabilities.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- A digital output pin for controlling the relay
|
||||
- ESP-32 microcontroller
|
||||
- Modbus-485 infrastructure for remote control
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Control of digital relay outputs (ON/OFF)
|
||||
- Modbus integration for remote control
|
||||
- State persistence and notification
|
||||
- Digital output pin management
|
||||
- Clean API for both direct and Modbus control
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [`Component`](../../src/Component.h) - Base class for all system components
|
||||
- [`ArduinoLog`](https://github.com/thijse/Arduino-Log) - Logging utility
|
||||
- [`App`](../../src/App.h) - Application framework
|
||||
- [`enums.h`](../../src/enums.h) - System-wide enumeration definitions
|
||||
- [`config.h`](../../src/config.h) - System configuration
|
||||
- [`Modbus`](../../src/modbus/Modbus.h) - Modbus protocol implementation
|
||||
- [`ModbusTCP`](../../src/modbus/ModbusTCP.h) - Modbus TCP implementation
|
||||
- [`config-modbus.h`](../../src/config-modbus.h) - Modbus configuration
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Relay --> Component
|
||||
Relay --> ArduinoLog
|
||||
Relay --> App
|
||||
Relay --> enums
|
||||
Relay --> config
|
||||
Relay --> Modbus
|
||||
Relay --> ModbusTCP
|
||||
Relay --> configmodbus[config-modbus.h]
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The Relay component maintains a simple state machine transitioning between ON and OFF states, controllable both via direct commands and Modbus.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
OFF --> ON: setValue(true) / Modbus Write(1)
|
||||
ON --> OFF: setValue(false) / Modbus Write(0)
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing batch operations for applications requiring multiple relay controls
|
||||
- Evaluate if digital write operations should be debounced or rate-limited in high-frequency scenarios
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add optional authorization for relay state changes
|
||||
- Implement validation logic for Modbus commands based on system state or conditions
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure relay state changes are properly logged for audit in systems requiring operation traceability
|
||||
- Consider adding timing constraints for safety-critical applications
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- For critical applications, implement a watchdog mechanism to set relays to a safe state if communication is lost
|
||||
- When controlling high-power relays, consider implementing safety checks before switching states
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This example shows how to instantiate and register a Relay component within the main application:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_RELAY_0
|
||||
relay_0 = new Relay(
|
||||
this, // owner
|
||||
PIN_RELAY_0, // pin
|
||||
ID_RELAY_0, // id
|
||||
RELAY_0_MB_ADDR // modbusAddress
|
||||
);
|
||||
if (relay_0)
|
||||
{
|
||||
components.push_back(relay_0);
|
||||
Log.infoln(F("Relay_0 initialized. Pin:%d, ID:%d, MB:%d"),
|
||||
PIN_RELAY_0, ID_RELAY_0, RELAY_0_MB_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("Relay_0 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
152
docs-c/components/RestServer.md
Normal file
152
docs-c/components/RestServer.md
Normal file
@ -0,0 +1,152 @@
|
||||
---
|
||||
title: "REST Server Component Documentation"
|
||||
description: "Documentation for the RESTServer component which provides HTTP and WebSocket APIs for Modbus communication"
|
||||
keywords: ["REST", "API", "WebSocket", "Modbus", "ESP32"]
|
||||
---
|
||||
|
||||
## REST Server
|
||||
|
||||
**Path**: [`src/components/RestServer.cpp`](../src/components/RestServer.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
The RESTServer component provides a RESTful API and WebSocket interface for interacting with the Modbus system, allowing remote monitoring and control of registers and coils. It serves static files from the filesystem and implements a comprehensive API for system monitoring and Modbus operations.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- WiFi or Ethernet connectivity
|
||||
- ESP32 with sufficient memory for web server operation
|
||||
- LittleFS filesystem for serving static files (optional, enabled via `ENABLE_LITTLEFS`)
|
||||
- WebSocket support (optional, enabled via `ENABLE_WEBSOCKET`)
|
||||
|
||||
## FEATURES
|
||||
|
||||
- RESTful API for Modbus operations (read/write registers and coils)
|
||||
- WebSocket interface for real-time updates and commands
|
||||
- Serves static files from the filesystem (HTML, CSS, JS)
|
||||
- System information and status endpoint
|
||||
- Log level control
|
||||
- RTU operation queue monitoring
|
||||
- CORS support for cross-origin requests
|
||||
- Pagination support for large datasets
|
||||
- JSON-based communication format
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) - Asynchronous web server library
|
||||
- [AsyncJson](https://github.com/me-no-dev/ESPAsyncWebServer) - JSON support for the async web server
|
||||
- [ArduinoJson](https://arduinojson.org/) - JSON parsing and serialization
|
||||
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - Logging utility
|
||||
- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP) - Asynchronous TCP library
|
||||
- [Component](../src/Component.h) - Base component class
|
||||
- [Bridge](../src/Bridge.h) - System bridge
|
||||
- [ModbusTCP](../src/modbus/ModbusTCP.h) - Modbus TCP implementation
|
||||
- [LittleFS](https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html) - Filesystem for static files
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
RESTServer --> ESPAsyncWebServer
|
||||
RESTServer --> AsyncJson
|
||||
RESTServer --> ArduinoJson
|
||||
RESTServer --> ArduinoLog
|
||||
RESTServer --> AsyncTCP
|
||||
RESTServer --> Component
|
||||
RESTServer --> Bridge
|
||||
RESTServer --> ModbusTCP
|
||||
RESTServer --> LittleFS[LittleFS "optional"]
|
||||
RESTServer --> WebSocket[AsyncWebSocket "optional"]
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The RESTServer handles API requests and WebSocket communications for interfacing with the Modbus system.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialize
|
||||
Initialize --> SetupRoutes
|
||||
SetupRoutes --> Ready
|
||||
|
||||
Ready --> HandleHTTPRequest: HTTP Request
|
||||
HandleHTTPRequest --> ServeStaticFile: File Request
|
||||
HandleHTTPRequest --> ProcessAPICall: API Request
|
||||
HandleHTTPRequest --> Ready
|
||||
|
||||
Ready --> HandleWebSocket: WebSocket Event
|
||||
HandleWebSocket --> ProcessCommand: Message Received
|
||||
HandleWebSocket --> NotifyClient: Client Connected
|
||||
HandleWebSocket --> CleanupClient: Client Disconnected
|
||||
HandleWebSocket --> Ready
|
||||
|
||||
Ready --> BroadcastUpdate: Modbus Data Changed
|
||||
BroadcastUpdate --> Ready
|
||||
|
||||
ProcessAPICall --> ReadModbusData: GET Request
|
||||
ProcessAPICall --> WriteModbusData: POST Request
|
||||
|
||||
ProcessCommand --> ReadModbusData: Read Command
|
||||
ProcessCommand --> WriteModbusData: Write Command
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider implementing message compression for WebSocket communications to reduce bandwidth usage
|
||||
- Optimize JSON serialization for large datasets to reduce memory usage
|
||||
- Implement caching mechanisms for frequently accessed static files
|
||||
- Add pagination for all resource-intensive endpoints to prevent memory issues
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement authentication for API endpoints and WebSocket connections
|
||||
- Add rate limiting to prevent abuse
|
||||
- Consider using HTTPS for encrypted communications
|
||||
- Validate all input parameters more strictly
|
||||
- Implement token-based authentication for long-lived WebSocket connections
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with REST API best practices
|
||||
- Implement proper error handling and status codes according to HTTP standards
|
||||
- Ensure WebSocket implementation complies with RFC 6455
|
||||
- Consider implementing OpenAPI/Swagger documentation for API endpoints
|
||||
- Add proper CORS configuration for security
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Keep WebSocket messages below the maximum size limit (currently 12KB)
|
||||
- Use pagination for large datasets to avoid memory issues
|
||||
- Monitor memory usage during operation, especially with large JSON responses
|
||||
- Consider implementing a websocket message queue for high-traffic systems
|
||||
- Add graceful disconnection handling for WebSocket clients
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This is how you would initialize and mount a RESTServer component:
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_WIFI
|
||||
// Create REST server component
|
||||
restServer = new RESTServer(
|
||||
WiFi.localIP(), // Local IP address from WiFi
|
||||
80, // HTTP port
|
||||
&modbusTCP, // Modbus TCP manager
|
||||
this // Owner component (Bridge)
|
||||
);
|
||||
|
||||
if (restServer) {
|
||||
components.push_back(restServer);
|
||||
Log.infoln(F("REST Server initialized on port 80"));
|
||||
} else {
|
||||
Log.errorln(F("REST Server initialization failed"));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
- [ESPAsyncWebServer Documentation](https://github.com/me-no-dev/ESPAsyncWebServer)
|
||||
- [RFC 6455 - The WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
|
||||
- [RESTful API Design Guide](https://restfulapi.net/)
|
||||
- [ArduinoJson Documentation](https://arduinojson.org/v6/doc/)
|
||||
126
docs-c/components/SAKO_VFD.md
Normal file
126
docs-c/components/SAKO_VFD.md
Normal file
@ -0,0 +1,126 @@
|
||||
```markdown
|
||||
---
|
||||
title: "SAKO VFD Component Documentation"
|
||||
description: "Documentation for the SAKO Variable Frequency Drive (VFD) control component for ESP32"
|
||||
keywords: ["VFD", "SAKO", "Modbus", "RS485", "motor control", "ESP32"]
|
||||
---
|
||||
|
||||
## SAKO VFD
|
||||
|
||||
**Path**: [`src/SAKO_VFD.cpp`](../src/SAKO_VFD.cpp)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
SAKO_VFD is a component for controlling SAKO Variable Frequency Drives via Modbus RTU over RS485. It provides comprehensive monitoring and control capabilities for industrial applications, allowing for frequency setting, direction control, status monitoring, and fault handling.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- ESP32 with RS485 interface capability
|
||||
- SAKO VFD connected via RS485
|
||||
- Modbus RTU communication enabled on the VFD
|
||||
- Proper connection to GND, A+, B- lines of RS485 bus
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Real-time monitoring of VFD parameters (frequency, current, power, torque)
|
||||
- Control of VFD operation (start, stop, reverse, frequency setting)
|
||||
- Fault detection and reset capability
|
||||
- Support for retract sequences
|
||||
- Statistical tracking of operational parameters
|
||||
- TCP Modbus mapping for remote monitoring and control
|
||||
- Configurable read intervals for performance optimization
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Component.h](../src/Component.h)
|
||||
- [ModbusRTU.h](../src/modbus/ModbusRTU.h)
|
||||
- [ModbusTypes.h](../src/modbus/ModbusTypes.h)
|
||||
- [xstatistics.h](../src/xstatistics.h)
|
||||
- [Logger.h](../src/Logger.h)
|
||||
- [Bridge.h](../src/Bridge.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
SAKO_VFD --> RTU_Base
|
||||
RTU_Base --> Component
|
||||
SAKO_VFD --> ModbusRTU
|
||||
SAKO_VFD --> ModbusTypes
|
||||
SAKO_VFD --> xstatistics
|
||||
SAKO_VFD --> Enums
|
||||
SAKO_VFD --> Config
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> STOPPED
|
||||
STOPPED --> ACCELERATING: run/reverse
|
||||
STOPPED --> ERROR: fault
|
||||
ACCELERATING --> RUNNING: reached setpoint
|
||||
ACCELERATING --> DECELERATING: new lower setpoint
|
||||
ACCELERATING --> ERROR: fault
|
||||
RUNNING --> DECELERATING: stop/new lower setpoint
|
||||
RUNNING --> ERROR: fault
|
||||
DECELERATING --> STOPPED: reached zero
|
||||
DECELERATING --> ACCELERATING: new higher setpoint
|
||||
DECELERATING --> ERROR: fault
|
||||
ERROR --> STOPPED: resetFault
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider adding a caching mechanism for registers that don't change frequently
|
||||
- Optimize read block configuration for specific SAKO VFD models
|
||||
- Implement batch writes for sending multiple parameters in a single transaction
|
||||
- Add power consumption tracking and optimization features
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add validation for frequency and command values before sending to VFD
|
||||
- Implement password protection for critical parameter changes
|
||||
- Add communication failure recovery mechanisms
|
||||
- Consider adding CRC validation for received data
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure proper handling of motor parameters according to manufacturer specifications
|
||||
- Implement safety shutdown procedures for emergency situations
|
||||
- Add support for compliance with IEC 61800 standards for variable speed drives
|
||||
- Consider implementing EN/IEC 60204-1 safety requirements
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Configure proper acceleration/deceleration times to prevent mechanical stress
|
||||
- Use motor auto-tuning functionality before production use
|
||||
- Implement proper fault handling and logging for diagnostic purposes
|
||||
- Consider adding thermal protection monitoring
|
||||
- Implement proper error handling and reporting for network communication failures
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_SAKO_VFD
|
||||
sakoVFD = new SAKO_VFD(
|
||||
MB_SAKO_VFD_SLAVE_ID, // Modbus slave ID
|
||||
SAKO_VFD_DEFAULT_READ_INTERVAL // Read interval in milliseconds
|
||||
);
|
||||
if (sakoVFD) {
|
||||
if (sakoVFD->setup() == E_OK) {
|
||||
components.push_back(sakoVFD);
|
||||
Log.infoln(F("SAKO VFD initialized. SlaveID: %d, Interval: %d ms"),
|
||||
MB_SAKO_VFD_SLAVE_ID, SAKO_VFD_DEFAULT_READ_INTERVAL);
|
||||
} else {
|
||||
Log.errorln(F("SAKO VFD setup failed."));
|
||||
delete sakoVFD;
|
||||
sakoVFD = nullptr;
|
||||
}
|
||||
} else {
|
||||
Log.errorln(F("SAKO VFD initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
104
docs-c/components/Sako-Registers.md
Normal file
104
docs-c/components/Sako-Registers.md
Normal file
@ -0,0 +1,104 @@
|
||||
---
|
||||
title: "Sako Modbus Register Enums"
|
||||
description: "Comprehensive documentation for the Sako drive Modbus register enumeration mappings"
|
||||
keywords: ["Sako", "VFD", "Modbus", "registers", "ESP32", "industrial-automation"]
|
||||
---
|
||||
|
||||
## Sako Modbus Register Enums
|
||||
|
||||
**Path**: [`./src/devices/sako/sako_modbus_registers.h`](./src/devices/sako/sako_modbus_registers.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
This component defines enumeration values for Sako VFD drive parameters accessible via Modbus. It provides a comprehensive mapping of control and configuration registers for Sako frequency inverters with descriptive comments on parameter functions and values.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Modbus RTU communication capability
|
||||
- RS485 interface connected to Sako VFD
|
||||
- Properly configured Modbus client implementation
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Complete parameter mapping for Sako VFD registers
|
||||
- Human-readable enumeration names that describe register purposes
|
||||
- Detailed comments for parameter options and value ranges
|
||||
- Hexadecimal address values with logical grouping by parameter sections
|
||||
- Support for all major drive control and configuration functions
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Modbus client implementation](./src/protocols/modbus/modbus_client.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Application --> SakoModbusRegisters
|
||||
SakoModbusRegisters --> ModbusClient
|
||||
ModbusClient --> RS485Hardware
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
The component provides enumeration constants that map to specific Modbus registers in the Sako VFD. It doesn't implement any behavior itself but provides the addressing information needed for the application to communicate with the device.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Application->>ModbusClient: Use Register Address from E_SAKO_PARAM
|
||||
ModbusClient->>SakoVFD: Send Modbus Request
|
||||
SakoVFD->>ModbusClient: Send Register Data
|
||||
ModbusClient->>Application: Return Result
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider organizing registers into separate enum classes for different parameter groups
|
||||
- Evaluate if a more structured approach like a map or class with methods would improve usability
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add validation ranges for each parameter to prevent sending invalid values
|
||||
- Consider adding read/write permissions to prevent accidental modification of critical parameters
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Verify all register addresses and descriptions against the latest Sako VFD documentation
|
||||
- Ensure compatibility with different Sako VFD series and firmware versions
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use constants from this enumeration rather than hardcoded values in application code
|
||||
- When sending values to the VFD, always check the allowed range from the parameter description
|
||||
- Consider implementing a higher-level interface that uses these enum values but provides type safety and validation
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
// Example of using the Sako register enums with a Modbus client
|
||||
ModbusClient* modbusClient = new ModbusClient(
|
||||
&Serial2,
|
||||
PIN_RS485_DE_RE,
|
||||
MODBUS_BAUD_RATE
|
||||
);
|
||||
|
||||
// Read motor control mode
|
||||
uint16_t controlMode;
|
||||
if (modbusClient->readHoldingRegister(
|
||||
SAKO_MODBUS_ADDRESS,
|
||||
static_cast<uint16_t>(E_SAKO_PARAM::E_SAKO_PARAM_P00_01_MOTOR_CONTROL_MODE),
|
||||
controlMode
|
||||
)) {
|
||||
Serial.printf("Motor control mode: %d\n", controlMode);
|
||||
}
|
||||
|
||||
// Set motor frequency to 50Hz (value needs to be scaled according to parameter specification)
|
||||
uint16_t frequencyValue = 5000; // 50.00Hz, assuming two decimal places
|
||||
modbusClient->writeHoldingRegister(
|
||||
SAKO_MODBUS_ADDRESS,
|
||||
static_cast<uint16_t>(E_SAKO_PARAM::E_SAKO_PARAM_P00_08_PRESET_FREQUENCY),
|
||||
frequencyValue
|
||||
);
|
||||
```
|
||||
|
||||
### References
|
||||
117
docs-c/components/SakoTypes.md
Normal file
117
docs-c/components/SakoTypes.md
Normal file
@ -0,0 +1,117 @@
|
||||
---
|
||||
title: "SAKO VFD Control Library"
|
||||
description: "Documentation for SAKO VFD (Variable Frequency Drive) interface component"
|
||||
keywords: [SAKO, VFD, Variable Frequency Drive, Modbus, ESP32, Industrial Control]
|
||||
---
|
||||
|
||||
## SAKO VFD Control Library
|
||||
|
||||
**Path**: [`src/SAKO.h`](../src/SAKO.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
A library for interfacing with SAKO Variable Frequency Drives (VFDs) via Modbus communication. This component provides standardized access to SAKO VFD registers, enabling monitoring and control of motors in industrial applications.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- RS-485 communication interface (hardware or software)
|
||||
- Modbus RTU protocol support
|
||||
- SAKO VFD with Modbus communication capability
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Comprehensive enumeration of SAKO VFD registers
|
||||
- Support for monitoring parameters (frequency, voltage, current, etc.)
|
||||
- Direction control (forward, reverse, jogging, etc.)
|
||||
- Error code definitions and handling
|
||||
- Parameter group communication access
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Modbus RTU Library](../src/modbusRTU.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
App --> SAKO
|
||||
SAKO --> ModbusRTU
|
||||
ModbusRTU --> UART
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Initialize
|
||||
Initialize --> Idle
|
||||
Idle --> ReadStatus: Poll Status
|
||||
Idle --> Control: Set Direction
|
||||
Idle --> ReadRegisters: Request Data
|
||||
ReadStatus --> Idle: Process Status
|
||||
Control --> Idle: Command Sent
|
||||
ReadRegisters --> Idle: Process Data
|
||||
ReadStatus --> ErrorHandling: Error Detected
|
||||
ErrorHandling --> Idle: Reset Error
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Optimize polling frequency based on application requirements
|
||||
- Consider implementing caching mechanism for frequently accessed registers
|
||||
- Add prioritization for critical status parameters
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Implement validation for register values before writing
|
||||
- Add support for communication timeouts
|
||||
- Consider checksum validation for critical commands
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Verify compatibility with all SAKO VFD models
|
||||
- Ensure compliance with industrial communication standards
|
||||
- Document parameter ranges according to SAKO specifications
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Maintain a minimum poll interval of 50ms to avoid bus contention
|
||||
- Use parameter group access addresses as specified in the SAKO manual
|
||||
- Implement error handling and retry logic for communication failures
|
||||
- Consider using separate tasks for status monitoring and control operations
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef ENABLE_SAKO_VFD
|
||||
sakoVFD = new SAKOVFD(
|
||||
this, // owner
|
||||
&modbus, // modbus interface
|
||||
SAKO_VFD_SLAVE_ADDR, // modbus slave address
|
||||
SAKO_VFD_ID // component ID
|
||||
);
|
||||
|
||||
if (sakoVFD) {
|
||||
components.push_back(sakoVFD);
|
||||
Log.infoln(F("SAKO VFD initialized. Slave Address: %d, ID: %d"),
|
||||
SAKO_VFD_SLAVE_ADDR, SAKO_VFD_ID);
|
||||
|
||||
// Configure monitoring parameters
|
||||
sakoVFD->enableMonitoring(E_SAKO_MON::E_SAKO_MON_RUNNING_FREQUENCY_HZ, true);
|
||||
sakoVFD->enableMonitoring(E_SAKO_MON::E_SAKO_MON_OUTPUT_CURRENT_A, true);
|
||||
sakoVFD->enableMonitoring(E_SAKO_MON::E_SAKO_MON_OUTPUT_VOLTAGE_V, true);
|
||||
}
|
||||
else {
|
||||
Log.errorln(F("SAKO VFD initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
The SAKO VFD component uses parameter group communication access addresses as defined in the SAKO VFD manual:
|
||||
- P0 ~ PE Group: 0xF000 - 0xFEFF
|
||||
- A0 ~ AC Group: 0xA000 - 0xACFF
|
||||
- U0 Group (Monitoring): 0x7000 - 0x70FF
|
||||
|
||||
For detailed information about specific registers and their meanings, refer to the SAKO VFD Operation Manual.
|
||||
125
docs-c/components/StatusLight.md
Normal file
125
docs-c/components/StatusLight.md
Normal file
@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "StatusLight - LED Status Indicator Component"
|
||||
description: "A component for controlling a status LED with simple on/off and blinking capabilities"
|
||||
keywords: ["ESP32", "status LED", "indicator", "modbus", "feedback"]
|
||||
---
|
||||
|
||||
## StatusLight
|
||||
|
||||
**Path**: [`src/StatusLight.h`](../../src/StatusLight.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
StatusLight is a component for controlling a status LED, providing simple on/off and blinking capabilities. It supports Modbus integration for remote monitoring and control of the status indicator.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- **Hardware**:
|
||||
- Digital GPIO pin for controlling an LED
|
||||
- **Software**:
|
||||
- Configuration for pin assignment in `config.h`
|
||||
- Modbus address configuration in `config-modbus.h`
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Steady on/off LED control
|
||||
- Blinking functionality with configurable interval
|
||||
- Modbus integration for remote monitoring and control
|
||||
- Support for multiple instances with different Modbus addresses
|
||||
- Component state tracking
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Arduino.h](https://github.com/espressif/arduino-esp32)
|
||||
- [ArduinoLog.h](https://github.com/thijse/Arduino-Log)
|
||||
- [Component.h](../../src/Component.h)
|
||||
- [macros.h](../../src/macros.h)
|
||||
- [xmath.h](../../src/xmath.h)
|
||||
- [Bridge.h](../../src/Bridge.h)
|
||||
- [enums.h](../../src/enums.h)
|
||||
- [config.h](../../src/config.h)
|
||||
- [config-modbus.h](../../src/config-modbus.h)
|
||||
- [modbus/ModbusTCP.h](../../src/modbus/ModbusTCP.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
StatusLight --> Component
|
||||
StatusLight --> Bridge
|
||||
StatusLight --> Arduino
|
||||
StatusLight --> ArduinoLog
|
||||
StatusLight --> macros
|
||||
StatusLight --> xmath
|
||||
StatusLight --> enums
|
||||
StatusLight --> config
|
||||
StatusLight --> configmodbus
|
||||
StatusLight --> ModbusTCP
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> OFF
|
||||
OFF --> ON: set(1)
|
||||
ON --> OFF: set(0)
|
||||
OFF --> BLINK: set(0,1)
|
||||
ON --> BLINK: set(1,1)
|
||||
BLINK --> OFF: set(0,0)
|
||||
BLINK --> ON: set(1,0)
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Consider using hardware PWM for smoother blinking effects
|
||||
- Review blinking implementation for efficiency (currently using polling in loop)
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add validation for input parameters in set() method
|
||||
- Consider authentication for Modbus write operations
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure blinking rates are appropriate for industrial environments
|
||||
- Comply with industrial standards for visual indicators
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use hardware with appropriate LED drivers for high-brightness applications
|
||||
- Consider adding additional blink patterns for varied status indications
|
||||
- Add support for RGB LEDs for multi-state visualization
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
Below is an example of how to initialize and use the StatusLight component:
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_STATUS_LIGHT
|
||||
statusLight = new StatusLight(
|
||||
this, // owner
|
||||
PIN_STATUS_LIGHT, // pin
|
||||
COMPONENT_KEY_FEEDBACK_0, // id
|
||||
MB_MONITORING_STATUS_FEEDBACK_0 // modbusAddress
|
||||
);
|
||||
if (statusLight)
|
||||
{
|
||||
components.push_back(statusLight);
|
||||
Log.infoln(F("StatusLight initialized. Pin:%d, ID:%d, MB:%d"),
|
||||
PIN_STATUS_LIGHT, COMPONENT_KEY_FEEDBACK_0,
|
||||
MB_MONITORING_STATUS_FEEDBACK_0);
|
||||
|
||||
// Example usage
|
||||
statusLight->on(); // Turn the LED on
|
||||
// statusLight->off(); // Turn the LED off
|
||||
// statusLight->setBlink(true); // Make the LED blink
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("StatusLight initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
136
docs-c/components/StepperController.md
Normal file
136
docs-c/components/StepperController.md
Normal file
@ -0,0 +1,136 @@
|
||||
---
|
||||
title: "Stepper Controller"
|
||||
description: "A component for controlling stepper motors with Modbus integration, direction control, and overload protection."
|
||||
keywords: ["ESP-32", "stepper motor", "Modbus", "motor control", "industrial automation"]
|
||||
---
|
||||
|
||||
## StepperController
|
||||
|
||||
**Path**: [`src/StepperController.h`](../src/StepperController.h)
|
||||
|
||||
**Revision History**: Initial documentation
|
||||
|
||||
StepperController is a component designed for precise control of stepper motors in industrial applications. It provides Modbus integration through ModbusValue, allowing remote control of motor speed and direction while monitoring status and overload conditions.
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
- Hardware:
|
||||
- Direction pin (GPIO)
|
||||
- Pulse pin (GPIO)
|
||||
- Feedback pin (GPIO) for monitoring motor status
|
||||
- Overload pin (analog input) for detecting motor overload
|
||||
- Compatible stepper motor driver
|
||||
- Software:
|
||||
- AccelStepper library
|
||||
- Modbus capabilities for remote control
|
||||
|
||||
## FEATURES
|
||||
|
||||
- Control stepper motor speed and direction via Modbus
|
||||
- Pulse width configuration for different stepper driver requirements
|
||||
- Overload detection for motor protection
|
||||
- Status monitoring (running, idle, error states)
|
||||
- Speed clamping for safety
|
||||
- Bidirectional control
|
||||
- Configurable motor parameters
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
- [Arduino.h](https://github.com/arduino/ArduinoCore-avr/blob/master/cores/arduino/Arduino.h)
|
||||
- [ArduinoLog.h](https://github.com/thijse/Arduino-Log)
|
||||
- [osr-base.h](../src/osr-base.h)
|
||||
- [App.h](../src/App.h)
|
||||
- [Addon.h](../src/Addon.h)
|
||||
- [Component.h](../src/Component.h)
|
||||
- [ModbusValue.h](../src/ModbusValue.h)
|
||||
- [types.h](../src/types.h)
|
||||
- [AccelStepper.h](https://www.airspayce.com/mikem/arduino/AccelStepper/)
|
||||
- [xmath.h](../src/xmath.h)
|
||||
- [features.h](../src/features.h)
|
||||
- [enums.h](../src/enums.h)
|
||||
- [config.h](../src/config.h)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
StepperController --> Component
|
||||
StepperController --> ModbusValue
|
||||
StepperController --> AccelStepper
|
||||
Component --> osrBase
|
||||
ModbusValue --> types
|
||||
StepperController --> xmath
|
||||
```
|
||||
|
||||
## BEHAVIOUR
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> MOTOR_IDLE
|
||||
MOTOR_IDLE --> MOTOR_RUNNING: speed > 0
|
||||
MOTOR_RUNNING --> MOTOR_IDLE: speed = 0
|
||||
MOTOR_RUNNING --> MOTOR_OVERLOAD: isOverloaded() == true
|
||||
MOTOR_OVERLOAD --> MOTOR_RUNNING: isOverloaded() == false
|
||||
MOTOR_RUNNING --> MOTOR_ERROR: hardware failure
|
||||
MOTOR_ERROR --> MOTOR_IDLE: reset
|
||||
MOTOR_UNKNOWN --> [*]
|
||||
```
|
||||
|
||||
## TODOS
|
||||
|
||||
### PERFORMANCE
|
||||
|
||||
- Add acceleration profiles for smoother movement
|
||||
- Implement microstepping control for higher precision
|
||||
- Optimize interrupt handling for more precise timing
|
||||
|
||||
### SECURITY
|
||||
|
||||
- Add parameter validation before applying motor settings
|
||||
- Implement authentication for Modbus control commands
|
||||
- Add motor limits based on system conditions
|
||||
|
||||
### COMPLIANCE
|
||||
|
||||
- Ensure compliance with motor manufacturer specifications
|
||||
- Verify compatibility with industrial Modbus implementations
|
||||
- Review power management for energy efficiency standards
|
||||
|
||||
### RECOMMENDATIONS
|
||||
|
||||
- Use shielded cables for motor connections to reduce EMI
|
||||
- Configure appropriate current limits on the stepper driver
|
||||
- Implement a soft start mechanism for heavy loads
|
||||
- Add emergency stop functionality for safety-critical applications
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
```cpp
|
||||
#ifdef PIN_STEPPER_0
|
||||
stepperController_0 = new StepperController(
|
||||
this, // owner
|
||||
PIN_STEPPER_0_DIR, // dirPin
|
||||
PIN_STEPPER_0_PULSE, // pulsePin
|
||||
PIN_STEPPER_0_FEEDBACK, // feedbackPin
|
||||
PIN_STEPPER_0_OVERLOAD, // overloadPin
|
||||
STEPPER_0_ENABLED, // enabled
|
||||
STEPPER_0_SPEED, // speed
|
||||
STEPPER_0_PULSE_WIDTH, // pulseWidth
|
||||
STEPPER_0_DIR, // dir
|
||||
ID_STEPPER_0, // id
|
||||
STEPPER_0_MB_ADDR // addressStart
|
||||
);
|
||||
|
||||
if (stepperController_0)
|
||||
{
|
||||
components.push_back(stepperController_0);
|
||||
Log.infoln(F("StepperController_0 initialized. Dir:%d, Pulse:%d, Speed:%d, ID:%d, MB:%d"),
|
||||
PIN_STEPPER_0_DIR, PIN_STEPPER_0_PULSE, STEPPER_0_SPEED,
|
||||
ID_STEPPER_0, STEPPER_0_MB_ADDR);
|
||||
}
|
||||
else
|
||||
{
|
||||
Log.errorln(F("StepperController_0 initialization failed."));
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
### References
|
||||
0
docs-c/src/LEDFeedback.cpp
Normal file
0
docs-c/src/LEDFeedback.cpp
Normal file
@ -13,6 +13,7 @@
|
||||
- Ensure the generated Markdown adheres to standard linting rules.
|
||||
- The generated Markdown document must follow the specific layout provided below.
|
||||
- The component's C++ source file will contain an example of how it is constructed and mounted; use this as a basis for the "Example" section in the documentation.
|
||||
- Do not comment or add thoughts, just output plain Markdown
|
||||
|
||||
## Layout
|
||||
|
||||
@ -26,7 +27,8 @@ The Markdown document must adhere to the following structure:
|
||||
|
||||
**Revision History**: Add a file revision entry in the header to track modifications. For the initial documentation, use "Initial documentation". Skip this if a revision history already exists !
|
||||
|
||||
A short description of the component.
|
||||
A short description of the component, highlight features
|
||||
|
||||
|
||||
## REQUIREMENTS
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
kbot-d --router2=openai --model=anthropic/claude-3.7-sonnet \
|
||||
--prompt=./scripts/docs-s.md \
|
||||
--each=./src/Value*.h \
|
||||
kbot-d --model=anthropic/claude-3.7-sonnet \
|
||||
--prompt=./scripts/docs-c.md \
|
||||
--each=./src/*.h \
|
||||
--globExtension=match-cpp \
|
||||
--wrap2=meta \
|
||||
--mode=completion \
|
||||
--filters=markdown \
|
||||
--preferences=none \
|
||||
--filters=code \
|
||||
--dst='./docs/${SRC_NAME}.md'
|
||||
--exclude='./docs-c/${SRC_NAME}*.md' \
|
||||
--dst='./docs-c/${SRC_NAME}.md'
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user