firmware-base/docs/SerialMessage.md

title	description	keywords
SerialMessage Component	Serial communication component for handling command message parsing and processing	serial communication command message parsing ESP32 Modbus industrial

SerialMessage

Path: src/SerialMessage.cpp

Revision History: Initial documentation

A serial communication component that handles reading, parsing, and processing of command messages from a serial stream. This component provides buffered serial communication with configurable message parsing intervals for industrial applications.

REQUIREMENTS

Hardware

• Serial communication interface (UART)
• No specific pin requirements (uses provided Stream object)

Software Dependencies

• ArduinoLog library for logging
• Vector library for data structures
• Arduino Stream interface
• Component base class

Configuration

• SERIAL_RX_BUFFER_SIZE: Receive buffer size (default: 256 bytes)
• SERIAL_COMMAND_PARSE_INTERVAL: Message parsing interval (default: 50ms)

FEATURES

• Buffered serial message reading
• Command message parsing and validation
• Configurable message delimiters
• Serial connection status tracking
• Debug message handling with hex output
• Non-blocking message processing
• Integration with Component architecture
• Owner notification system for parsed messages

DEPENDENCIES

• Component - Base component class
• CommandMessage - Message structure and parsing
• ArduinoLog - Logging functionality
• Vector - Data structure library
• Arduino Stream - Serial communication interface

graph TD
    SerialMessage --> Component
    SerialMessage --> CommandMessage
    SerialMessage --> ArduinoLog
    SerialMessage --> Stream
    Component --> Owner[Owner Component]
    CommandMessage --> MessageParsing[Message Parsing Logic]

BEHAVIOUR

stateDiagram-v2
    [*] --> Setup
    Setup --> Idle
    Idle --> CheckInterval: loop()
    CheckInterval --> ReadMessage: interval elapsed
    CheckInterval --> Idle: interval not elapsed
    ReadMessage --> ParseMessage: message available
    ReadMessage --> Idle: no message
    ParseMessage --> ValidateMessage: parsing successful
    ParseMessage --> Idle: parsing failed
    ValidateMessage --> NotifyOwner: message valid
    ValidateMessage --> Idle: message invalid
    NotifyOwner --> Idle: owner notified
    Idle --> [*]: component destroyed

TODOS

PERFORMANCE

• Consider implementing circular buffer for improved memory efficiency
• Optimize string operations to reduce memory fragmentation
• Implement message queuing for high-frequency communication
• Add configurable buffer overflow handling

SECURITY

• Implement message authentication for command validation
• Add input sanitization for malformed messages
• Consider implementing rate limiting for message processing
• Add checksum validation for message integrity

COMPLIANCE

• Ensure compliance with Modbus serial communication standards
• Implement proper error handling according to industrial communication protocols
• Add support for standard industrial message formats

RECOMMENDATIONS

• Use hardware serial interfaces for better reliability
• Configure appropriate baud rates for industrial environments
• Implement proper error recovery mechanisms
• Consider using DMA for high-speed serial communication
• Add message statistics and monitoring capabilities

EXAMPLE

This section illustrates how the SerialMessage component is constructed and mounted:

#ifdef ENABLE_SERIAL_COMMANDS
  serialMessage = new SerialMessage(
      Serial,                    // stream (Hardware Serial)
      this                       // owner component
  );
  if (serialMessage)
  {
    components.push_back(serialMessage);
    Log.infoln(F("SerialMessage initialized. Stream: Hardware Serial"));
  }
  else
  {
    Log.errorln(F("SerialMessage initialization failed."));
  }
#endif

// Alternative with Serial1 for RS485 communication
#ifdef ENABLE_RS485_SERIAL
  rs485SerialMessage = new SerialMessage(
      Serial1,                   // stream (Hardware Serial1)
      this                       // owner component
  );
  if (rs485SerialMessage)
  {
    components.push_back(rs485SerialMessage);
    Log.infoln(F("RS485 SerialMessage initialized. Stream: Hardware Serial1"));
  }
  else
  {
    Log.errorln(F("RS485 SerialMessage initialization failed."));
  }
#endif

Message Handling Example

// Owner component implements onMessage to handle parsed commands
void MyComponent::onMessage(uint16_t id, uint8_t verb, uint8_t flags, 
                           const String& payload, Component* sender)
{
  if (sender == serialMessage)
  {
    Log.infoln(F("Received serial command: ID=%d, Verb=%d, Payload=%s"), 
               id, verb, payload.c_str());
    
    // Process the command based on ID and verb
    switch (id)
    {
      case COMMAND_SET_CONFIG:
        handleConfigCommand(verb, flags, payload);
        break;
      case COMMAND_GET_STATUS:
        handleStatusRequest(verb, flags, payload);
        break;
      default:
        Log.warningln(F("Unknown command ID: %d"), id);
        break;
    }
  }
}

References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}

str_replace ./docs/SerialMessage.md Now I'll create the documentation file for the SerialMessage component. create ./docs/SerialMessage.md --- title: "SerialMessage Component" description: "Serial communication component for handling command message parsing and processing" keywords: ["serial", "communication", "command", "message", "parsing", "ESP32", "Modbus", "industrial"] ---

SerialMessage

Path: src/SerialMessage.cpp

Revision History: Initial documentation

A serial communication component that handles reading, parsing, and processing of command messages from a serial stream. This component provides buffered serial communication with configurable message parsing intervals for industrial applications.

REQUIREMENTS

Hardware

• Serial communication interface (UART)
• No specific pin requirements (uses provided Stream object)

Software Dependencies

• ArduinoLog library for logging
• Vector library for data structures
• Arduino Stream interface
• Component base class

Configuration

• SERIAL_RX_BUFFER_SIZE: Receive buffer size (default: 256 bytes)
• SERIAL_COMMAND_PARSE_INTERVAL: Message parsing interval (default: 50ms)

FEATURES

• Buffered serial message reading
• Command message parsing and validation
• Configurable message delimiters
• Serial connection status tracking
• Debug message handling with hex output
• Non-blocking message processing
• Integration with Component architecture
• Owner notification system for parsed messages

DEPENDENCIES

• Component - Base component class
• CommandMessage - Message structure and parsing
• ArduinoLog - Logging functionality
• Vector - Data structure library
• Arduino Stream - Serial communication interface

graph TD
    SerialMessage --> Component
    SerialMessage --> CommandMessage
    SerialMessage --> ArduinoLog
    SerialMessage --> Stream
    Component --> Owner[Owner Component]
    CommandMessage --> MessageParsing[Message Parsing Logic]

BEHAVIOUR

stateDiagram-v2
    [*] --> Setup
    Setup --> Idle
    Idle --> CheckInterval: loop()
    CheckInterval --> ReadMessage: interval elapsed
    CheckInterval --> Idle: interval not elapsed
    ReadMessage --> ParseMessage: message available
    ReadMessage --> Idle: no message
    ParseMessage --> ValidateMessage: parsing successful
    ParseMessage --> Idle: parsing failed
    ValidateMessage --> NotifyOwner: message valid
    ValidateMessage --> Idle: message invalid
    NotifyOwner --> Idle: owner notified
    Idle --> [*]: component destroyed

TODOS

PERFORMANCE

• Consider implementing circular buffer for improved memory efficiency
• Optimize string operations to reduce memory fragmentation
• Implement message queuing for high-frequency communication
• Add configurable buffer overflow handling

SECURITY

• Implement message authentication for command validation
• Add input sanitization for malformed messages
• Consider implementing rate limiting for message processing
• Add checksum validation for message integrity

COMPLIANCE

• Ensure compliance with Modbus serial communication standards
• Implement proper error handling according to industrial communication protocols
• Add support for standard industrial message formats

RECOMMENDATIONS

• Use hardware serial interfaces for better reliability
• Configure appropriate baud rates for industrial environments
• Implement proper error recovery mechanisms
• Consider using DMA for high-speed serial communication
• Add message statistics and monitoring capabilities

EXAMPLE

This section illustrates how the SerialMessage component is constructed and mounted:

#ifdef ENABLE_SERIAL_COMMANDS
  serialMessage = new SerialMessage(
      Serial,                    // stream (Hardware Serial)
      this                       // owner component
  );
  if (serialMessage)
  {
    components.push_back(serialMessage);
    Log.infoln(F("SerialMessage initialized. Stream: Hardware Serial"));
  }
  else
  {
    Log.errorln(F("SerialMessage initialization failed."));
  }
#endif

// Alternative with Serial1 for RS485 communication
#ifdef ENABLE_RS485_SERIAL
  rs485SerialMessage = new SerialMessage(
      Serial1,                   // stream (Hardware Serial1)
      this                       // owner component
  );
  if (rs485SerialMessage)
  {
    components.push_back(rs485SerialMessage);
    Log.infoln(F("RS485 SerialMessage initialized. Stream: Hardware Serial1"));
  }
  else
  {
    Log.errorln(F("RS485 SerialMessage initialization failed."));
  }
#endif

Message Handling Example

// Owner component implements onMessage to handle parsed commands
void MyComponent::onMessage(uint16_t id, uint8_t verb, uint8_t flags, 
                           const String& payload, Component* sender)
{
  if (sender == serialMessage)
  {
    Log.infoln(F("Received serial command: ID=%d, Verb=%d, Payload=%s"), 
               id, verb, payload.c_str());
    
    // Process the command based on ID and verb
    switch (id)
    {
      case COMMAND_SET_CONFIG:
        handleConfigCommand(verb, flags, payload);
        break;
      case COMMAND_GET_STATUS:
        handleStatusRequest(verb, flags, payload);
        break;
      default:
        Log.warningln(F("Unknown command ID: %d"), id);
        break;
    }
  }
}

References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}

str_replace ./docs/SerialMessage.md Now I'll create the documentation file for the SerialMessage component.

The documentation has been successfully created! Here's a summary of what was generated:

SerialMessage Component Documentation

The documentation file has been created at ./docs/SerialMessage.md with the following key sections:

Key Features Documented:

• Serial Communication: Handles reading and parsing of command messages from serial streams
• Buffered Processing: Uses configurable buffer size and parsing intervals
• Message Validation: Parses and validates incoming command messages
• Owner Notification: Integrates with the Component architecture to notify owners of parsed messages

Technical Details:

• Requirements: Hardware serial interface, various software dependencies
• Configuration: Configurable buffer size (256 bytes default) and parsing interval (50ms default)
• Dependencies: Component base class, CommandMessage, ArduinoLog, Vector library
• Behavior: State machine showing message processing flow

Documentation Structure:

• Standard frontmatter for Astro static site generator
• Comprehensive feature list and requirements
• Mermaid diagrams for dependencies and behavior
• TODO sections covering performance, security, compliance, and recommendations
• Practical examples showing component construction and message handling

The documentation is ready for use in an Astro static site and follows all the specified formatting requirements including proper Markdown linting standards.