Serial Devices

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 EZO, 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 EZO| F[Configure EZO 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 EZO		Professional-grade water quality and environmental sensors	pH, EC, ORP, DO, temperature, humidity, CO₂, pressure
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
sendCommand	Command sent before each read	R
terminator	Line terminator (CR, LF, CRLF)	CR

Common Baud Rates

Baud Rate	Use Case
9600	Default for all Atlas EZO circuits, 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 EZO-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 EZO Integration

Atlas Scientific EZO circuits are industry-standard embedded sensing modules used in hydroponics, aquariums, industrial water quality, and scientific research. Krill supports the full EZO lineup via UART (USB) through the Atlas Scientific Gen 2 Electrically Isolated USB EZO Carrier Board.

Supported EZO Circuits

Circuit	Model	Default I2C Addr	Measurement	Output Format	Unit
EZO-pH	EZO-pH	99	Acidity / alkalinity	7.00	pH (0–14)
EZO-EC	EZO-EC	100	Electrical conductivity	800,640,1.19,0.56	µS/cm, TDS ppm, salinity PSU, SG
EZO-ORP	EZO-ORP	98	Oxidation-reduction potential	+250.33	mV
EZO-DO	EZO-DO	97	Dissolved oxygen	8.37,97.2	mg/L, % saturation
EZO-RTD	EZO-RTD	102	Temperature (RTD probe)	25.00	°C or °F
EZO-HUM	EZO-HUM	111	Humidity, temperature, dew point	31.8,18.1,100.0	%RH, °C, °C dew point
EZO-CO2	EZO-CO2	105	CO₂ concentration	400.00	ppm
EZO-O2	EZO-O2	108	Oxygen (gas-phase)	20.95	% volume
EZO-PRS	EZO-PRS	106	Pressure	16.30	psi
EZO-RGB	EZO-RGB	112	Color (R/G/B/lux)	223,164,109,3012	R, G, B (0–255), lux
EZO-PMP / PMP-L	EZO-PMP	103	Peristaltic pump control	command/response	mL

UART Settings (all EZO circuits)

All Atlas EZO circuits share identical default UART parameters when accessed via the USB carrier board:

Parameter	Value
Baud rate	9600
Data bits	8
Parity	None
Stop bits	1
Flow control	None
Line terminator	CR (\r)
Read command	R
Encoding	ASCII

Use the Atlas EZO Quick Setup preset in the Krill serial device editor to apply these settings automatically.

Multi-Value Outputs

Several EZO circuits return multiple comma-separated values per read (EC returns 4, DO and HUM return 3, RGB returns 4). The raw comma-separated string is stored in the Data Point snapshot. Use a Lambda or Compute executor to split and route individual values:

# Example Lambda: extract conductivity from EZO-EC response "800,640,1.19,0.56"
parts = value.split(",")
conductivity = float(parts[0])   # µS/cm
tds_ppm      = float(parts[1])   # TDS in ppm
salinity     = float(parts[2])   # salinity PSU
sg           = float(parts[3])   # specific gravity

Temperature Compensation

pH, EC, and DO readings are affected by temperature. Assign an EZO-RTD temperature probe as the compensation source for each circuit to improve accuracy. Send the temperature compensation command before each read:

T,<temperature>    # e.g. T,25.00 (sets compensation to 25°C)
R                  # triggers a reading

As of Atlas IoT firmware v4.1.0, temperature compensation is not automatically assigned — you must explicitly configure the RTD source for each EZO circuit that supports it.

USB Gen 2 Carrier Board

The Gen 2 Electrically Isolated USB EZO Carrier Board presents each EZO circuit as a separate USB-CDC serial device. Connect the carrier board and each slot appears as /dev/ttyUSB* (or /dev/serial/by-id/...). The electrical isolation prevents ground loops when multiple EZO circuits share a common water sample.

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; Atlas EZO defaults to 9600
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
*RE response	EZO circuit read error	Check probe connection; ensure probe is submerged
CSV parse error	Wrong EZO circuit type	Confirm which circuit is in each carrier board slot

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 (required for multi-value EZO output)
• 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.

---

Last verified: 2026-06-04