Skip to content

Progress Log: Serial Communication Guide Documentation

Task Description

Created detailed documentation for the Kurikintons serial communication protocol, explaining:

  • Command reception format (3-byte packets)
  • Sensor data transmission format
  • Stability improvements in v1.1.0
  • Python and C++ usage examples
  • Troubleshooting guide
  • Performance characteristics

This documentation serves as a reference for DAQ system developers integrating with the detector firmware.

Outcome

✅ Successfully created comprehensive serial communication documentation with:

  • Command Format: Explained 3-byte command structure (channel, data1, data2)
  • Data Transmission: Documented sensor data output format with example values
  • Stability Enhancements: Detailed 4 key improvements (timeout sync, retry mechanism, buffer management, timing)
  • Backward Compatibility: Clarified that data format remains unchanged
  • Usage Examples: Provided Python and C++ code samples for DAQ integration
  • Troubleshooting: Added common issues and solutions
  • Performance Table: Documented baud rate, timeouts, buffer limits, and response times

Build verified: No compilation errors Documentation integrated into project structure

Learnings

  1. Documentation Importance: Comprehensive protocol documentation is essential for cross-team integration
  2. Format Stability: Maintaining data format compatibility while improving internal stability is crucial for existing DAQ systems
  3. Clear Examples: Code examples in multiple languages help different teams integrate quickly
  4. Troubleshooting Guide: Practical troubleshooting reduces support burden and user frustration

Technical Reference

Command Reception Format

Commands are received as 3-byte packets:

Byte 0: Channel Number (1-3)
Byte 1: Data 1 (DAC setting - first byte)
Byte 2: Data 2 (DAC setting - second byte)

Example Commands:

0x01 0x14 0x3C  → Channel 1, DAC value 0x143C
0x02 0x14 0x9C  → Channel 2, DAC value 0x149C
0x03 0x14 0x18  → Channel 3, DAC value 0x1418

Response:

  • Valid command: Echoes the command bytes in decimal and binary, then applies settings
  • Invalid command (val1 == 0xFF): Sends "dame" (invalid)

Sensor Data Format

When cosmic ray is detected, the system sends:

signal1 signal2 signal3 adc_value temperature pressure humidity

Example output:

1 0 0 512 23.45 1013.25 45.6
2 1 1 480 23.42 1013.22 45.8

Format Details:

Field Type Range Unit
signal1 int 0-10+ count
signal2 int 0-10+ count
signal3 int 0-10+ count
adc_value int 0-4095 raw
temperature float -40~85 °C
pressure float 300~1100 hPa
humidity float 0~100 %RH

Configuration Parameters

Stability parameters are tunable via macros in include/serial_communication.h:

#define SERIAL_MAX_RETRIES 3         // Retry attempts
#define SERIAL_TIMEOUT_MS 100        // Timeout in milliseconds
#define SERIAL_READ_DELAY_MS 5       // Delay between reads
#define SERIAL_BUFFER_CLEAN_SIZE 256 // Max bytes to flush

Usage Examples

Python Example:

import serial

# Open serial connection
ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1)

# Send command to channel 1
command = bytes([0x01, 0x14, 0x3C])
ser.write(command)

# Read response (echoed command)
response = ser.read(3)
print(f"Channel: {response[0]}")
print(f"Data1: {response[1]:08b}")  # Binary format
print(f"Data2: {response[2]:08b}")

# Read sensor data
line = ser.readline().decode().strip()
signal1, signal2, signal3, adc, temp, pres, humid = line.split()
print(f"Detected: {signal1} {signal2} {signal3}")
print(f"Temperature: {float(temp):.2f}°C")

C++ Example:

#include <serial/serial.h>

serial::Serial ser("/dev/ttyUSB0", 115200);

// Send command
uint8_t cmd[3] = {0x01, 0x14, 0x3C};
ser.write(cmd, 3);

// Read and parse response
uint8_t response[3];
ser.read(response, 3);
printf("Channel: %d\n", response[0]);

// Read sensor data
std::string line;
std::getline(ser, line);
// Parse: "1 0 0 512 23.45 1013.25 45.6"

Troubleshooting Guide

Symptoms: Commands not working properly

Possible Causes:

  1. Baud rate mismatch (must be 115200)
  2. Partial command being sent
  3. Serial cable quality issues

Solutions:

  1. Verify baud rate: task monitor to check output
  2. Ensure sending complete 3-byte commands
  3. Try shorter USB cable or add ferrite filter

Symptoms: Intermittent command failures

Cause: The enhanced stability should handle this, but if still occurring:

  1. Check for excessive noise on serial line
  2. Reduce baud rate if possible (reconfigure with platformio.ini)
  3. Verify USB power supply quality

Symptoms: Response garbled or missing

Possible Causes:

  1. Serial buffer overflow (too much data arriving)
  2. Timing issue between commands

Solutions:

  1. Add delays between commands (50ms minimum)
  2. Reduce sensor data output frequency if possible
  3. Check USB hub for power issues

Performance Characteristics

Parameter Value
Baud Rate 115200
Command Size 3 bytes
Command Timeout 100ms
Max Retries 3
Buffer Flush Limit 256 bytes
Byte Read Delay 5ms
Typical Response Time < 10ms

How to Monitor

View real-time communication:

# Using task
task monitor

# Using platformio directly
uv run platformio device monitor --baud 115200

References

Next Steps

  • Monitor user feedback on documentation clarity
  • Update documentation if new serial communication issues are discovered
  • Consider adding real-time data capture examples
  • Create automated tests for serial communication stability