Serial Device

Serial Devices: Hardware Communication Interface

Serial Device support enables communication with hardware devices connected via serial ports (USB, UART), providing integration with various sensors, microcontrollers, and IoT devices. Krill Server automatically detects and manages serial devices, making hardware integration seamless and accessible.

Overview

Serial devices are the physical bridge between the digital automation world and real-world sensors and actuators. Whether you’re connecting environmental sensors, scientific instruments, or microcontrollers, Serial Device support provides the communication layer needed to read data and send commands.

Key Features

• Auto-Detection: Automatically discovers serial devices connected to the server
• Multiple Device Types: Support for QTPY, Atlas Scientific, Zigbee, and generic serial devices
• Configurable Parameters: Set baud rate, timeouts, and communication intervals
• Bidirectional Communication: Read data from devices and write commands
• Data Point Integration: Automatically route serial data to Data Points
• Device Type Recognition: Intelligent identification of known device types
• Robust Error Handling: Graceful handling of connection issues

Serial Device Communication Flow

graph TD
    A[Serial Device Connected] --> B[Krill Server Detects Device]
    B --> C[Create Serial Device Node]
    C --> D{Device Type?}
    D -->|QTPY| E[Configure Python Protocol]
    D -->|Atlas| F[Configure I2C Protocol]
    D -->|Other| G[Configure Generic Serial]
    E --> H[Start Reading Loop]
    F --> H
    G --> H
    H --> I[Parse Device Output]
    I --> J[Update Child Data Points]
    J --> K[Trigger Automation]

Supported Device Types

Device Type	Icon	Description	Common Use Cases
QTPY		Adafruit QTPY microcontroller boards	Custom sensors, Python-based IoT
Atlas Scientific		Professional-grade water quality sensors	pH, EC, ORP, dissolved oxygen
Other		Generic serial devices	Any RS-232/USB serial device

How It Works

Serial Device processing operates through continuous monitoring:

1. Detection: Krill Server scans for connected serial ports on startup
2. Identification: Attempts to identify device type based on communication patterns
3. Node Creation: Creates Serial Device node for each detected device
4. Configuration: Applies appropriate settings (baud rate, protocol, timing)
5. Communication: Establishes serial connection with configured parameters
6. Data Reading: Reads data at configured intervals
7. Parsing: Parses device output into usable values
8. Distribution: Routes parsed data to child Data Points
9. Automation: Data Point updates trigger downstream automation

Configuration Options

Field	Description	Default
name	Display name for the device	Device identifier
hardwareId	Unique hardware identifier	Auto-detected
baudRate	Serial communication speed	9600
readTimeout	Read operation timeout (ms)	1000
writeTimeout	Write operation timeout (ms)	0
interval	Reading interval (ms)	0 (continuous)
operation	READ or WRITE mode	READ
address	I2C address (for Atlas)	0

Common Baud Rates

Baud Rate	Use Case
9600	Default, compatible with most devices
115200	High-speed devices, microcontrollers
19200	Industrial sensors
57600	GPS devices, fast sensors

Use Cases

Environmental Monitoring:

• pH sensors for hydroponics/aquariums
• Temperature and humidity probes
• Air quality sensors (CO2, VOC, particulates)
• Weather station instruments

Industrial Applications:

• PLCs and industrial controllers
• Motor controllers and drives
• Barcode and RFID readers
• Weighing scales and load cells

Scientific Instruments:

• Laboratory analyzers
• Data loggers
• Spectrophotometers
• Calibration equipment

IoT Prototyping:

• Arduino and ESP32 boards
• Raspberry Pi Pico
• Adafruit QTPY boards
• Custom microcontroller projects

Example Workflows

Water Quality Monitoring:

1. Serial Device: Atlas Scientific pH sensor
2. Data Points: pH, Temperature
3. Trigger: Low Threshold (pH < 6.0)
4. Executor: OutgoingWebHook (alert)
5. Executor: Pin Control (activate pH adjustment pump)

Environmental Data Logging:

1. Serial Device: QTPY with environmental sensors
2. Data Points: Temperature, Humidity, CO2
3. Trigger: Cron Timer (every 5 minutes)
4. Executor: Compute (hourly averages)
5. Executor: OutgoingWebHook (cloud upload)

Industrial Equipment Monitoring:

1. Serial Device: Motor controller
2. Data Points: Speed, Current, Temperature
3. Trigger: High Threshold (temperature > 80°C)
4. Executor: Logic Gate (safety check)
5. Executor: Pin Control (emergency stop)

Atlas Scientific Integration

Atlas Scientific sensors are industry-standard water quality instruments:

Supported Sensors:

• pH Sensor: Measure acidity/alkalinity (0-14 pH)
• EC Sensor: Electrical conductivity (µS/cm)
• ORP Sensor: Oxidation-reduction potential (mV)
• DO Sensor: Dissolved oxygen (mg/L)
• Temperature: RTD temperature probes

I2C Communication: Atlas sensors support I2C protocol for reliable multi-sensor setups on a single bus.

QTPY Integration

Adafruit QTPY boards provide versatile Python-programmable sensor platforms:

Features:

• CircuitPython support
• USB-C connectivity
• Compact form factor
• I2C, SPI, and GPIO capabilities
• Rich sensor library ecosystem

Example QTPY Setup:

1. Flash CircuitPython to QTPY
2. Write sensor reading script
3. Output data in parseable format
4. Krill reads and distributes to Data Points

Serial Communication Best Practices

• Stable Connections: Use quality cables and secure connections
• Proper Termination: Ensure correct line endings (CR, LF, CRLF)
• Error Handling: Implement retries for communication failures
• Data Validation: Validate parsed data before processing
• Grounding: Ensure proper electrical grounding
• Isolation: Consider optoisolators for industrial environments

Troubleshooting

Symptom	Possible Cause	Solution
No data	Wrong baud rate	Check device documentation
Garbled data	Baud rate mismatch	Match device baud rate
Intermittent	Loose connection	Check cables and connectors
Timeout errors	Device not responding	Increase timeout, check power
No detection	Permission issues	Check serial port permissions

Integration Points

• Data Points: Automatic routing of sensor readings
• Triggers: React to sensor thresholds
• Executors: Control devices via serial commands
• Lambda: Custom data parsing and processing
• MQTT: Bridge serial data to MQTT topics
• WebHooks: Send sensor data to cloud services

Linux Serial Permissions

On Linux systems, ensure the Krill Server user has access to serial ports:

# Add user to dialout group
sudo usermod -a -G dialout krill

# Or set permissions on specific port
sudo chmod 666 /dev/ttyUSB0

Device Connection Workflow

graph TD
    A[Connect Device to USB] --> B[System Creates /dev/ttyUSB*]
    B --> C[Krill Detects New Port]
    C --> D[Create Serial Device Node]
    D --> E[Configure Device Parameters]
    E --> F[Create Child Data Points]
    F --> G[Start Data Collection]
    G --> H[Automation Active]

Serial Devices are the foundation for physical world integration, enabling Krill to communicate with the vast ecosystem of serial-connected sensors, instruments, and controllers.