soil_sensor #

A Flutter package for reading Modbus RTU soil sensors (NPK, moisture, temperature, pH, and conductivity) over USB serial on Android and Windows.

Features #

• Enumerate connected USB serial devices on Android and Windows
• Connect and disconnect with configurable baud rate and Modbus slave address
• Read soil parameters via Modbus RTU FC03:
  • Basic sensors (3 registers): moisture (%), temperature (°C), conductivity (µS/cm)
  • Extended sensors (7 registers): + pH, nitrogen (mg/kg), phosphorus (mg/kg), potassium (mg/kg)
• Automatic fallback from extended to basic read when the sensor doesn't support NPK registers
• Configurable retry logic for noisy serial connections
• Typed SensorReading model with hasNpk and isRecent convenience getters

Supported platforms #

Getting started #

Add the dependency to your pubspec.yaml:

dependencies:
  soil_sensor: ^0.1.0

Android permissions #

Add USB host permission to AndroidManifest.xml:

<uses-feature android:name="android.hardware.usb.host" />

Windows #

No additional setup required — flutter_libserialport uses the native Windows serial API.

Usage #

import 'package:soil_sensor/soil_sensor.dart';

final service = SoilSensorService(baudRate: 9600, slaveAddress: 1);

// 1. List available devices
final devices = await service.listDevices();
print(devices); // e.g. ['COM3', 'COM4'] on Windows

// 2. Connect
await service.connect(devices.first);

// 3. Read sensor data
final reading = await service.readSensor();
print('Moisture:     ${reading.moisture} %');
print('Temperature:  ${reading.temperature} °C');
print('Conductivity: ${reading.conductivity} µS/cm');
print('pH:           ${reading.ph}');
if (reading.hasNpk) {
  print('Nitrogen:   ${reading.nitrogen} mg/kg');
  print('Phosphorus: ${reading.phosphorus} mg/kg');
  print('Potassium:  ${reading.potassium} mg/kg');
}

// 4. Disconnect when done
await service.disconnect();

API overview #

SoilSensorService #

The main entry point.

SensorReading #

Immutable value object returned by readSensor().

ModbusRtuService #

Low-level Modbus RTU framing primitives (advanced use). All methods are static.

Protocol details #

The sensor communicates over Modbus RTU (FC03 Read Holding Registers) via a USB-to-RS485 adapter that enumerates as a CDC USB serial device.

Hardware setup #

┌──────────────┐     USB      ┌─────────────────┐   RS485   ┌──────────────┐
│  Android /   │─────────────>│  USB-to-RS485   │──────────>│ Soil Sensor  │
│   Windows    │              │    Adapter      │  (A / B)  │              │
└──────────────┘              └─────────────────┘           └──────────────┘

Serial port settings #

Register map #

Basic sensors (3 registers — starting at 0x0000)

Extended sensors (7 registers — starting at 0x0000)

SoilSensorService.readSensor() automatically attempts the 7-register read first and falls back to 3 registers when the sensor returns exception code 0x02 (Illegal Data Address).

For full protocol details — frame format, CRC algorithm, timing requirements, error codes, and troubleshooting — see doc/MODBUS_RTU_PROTOCOL.md.

Additional information #

• Issues & feature requests: GitHub Issues
• Source code: github.com/sicrisembay/flutter_packages
• Contributions: Pull requests are welcome. Please open an issue first to discuss significant changes.