#modbus-moon

#Features

#Core protocol (src/lib/)

• Function codes — full Modbus Application Protocol V1.1b3 coverage: ReadCoils (0x01), ReadDiscreteInputs (0x02), ReadHoldingRegisters (0x03), ReadInputRegisters (0x04), WriteSingleCoil (0x05), WriteSingleRegister (0x06), WriteMultipleCoils (0x0F), WriteMultipleRegisters (0x10), ReadExceptionStatus (0x07), Diagnostics (0x08), GetCommEventCounter (0x0B), GetCommEventLog (0x0C), ReportServerId (0x11), ReadFileRecord (0x14), WriteFileRecord (0x15), MaskWriteRegister (0x16), ReadWriteMultipleRegisters (0x17), ReadFifoQueue (0x18), EncapsulatedInterfaceTransport (0x2B), plus Custom(Byte) for user-defined codes.
• CRC-16 Modbus RTU checksum (src/lib/crc.mbt).
• ADU serialization for both TCP (MBAP) and RTU (CRC) with CRC-validated deserialization (src/lib/adu.mbt).
• Exception codes with ExceptionCode enum and ExceptionResponse helper struct (src/lib/exception.mbt).
• Slave / unit id addressing with helpers (broadcast/min_device/max_device/tcp_device/is_*).
• Request / Response enums with to_pdu / from_pdu codec (src/lib/request.mbt, src/lib/response.mbt).
• Coil / word bit-packing helpers (coils_to_bytes, bytes_to_coils, coil_to_word, words_to_bytes, …).
• Typed aliases: Coil = Bool, Word = UInt16, Address = UInt16, Quantity = UInt16, SlaveId = Byte.

#Client (src/client/)

• Context[R : Runtime] — generic transport-agnostic client context (mirrors tokio-modbus::Context).
• Runtime trait — pluggable transport backend (send/recv/disconnect).
• ClientResult[T] — two-layer Result separating transport errors from server-reported exception codes.
• Reader trait — typed read methods for coils, discrete inputs, holding/input registers, and ReadWriteMultipleRegisters.
• Writer trait — typed write methods for single/multiple coils & registers, and MaskWriteRegister.

#Server (src/server/)

• Service trait — request → Result[Response, ExceptionCode] (mirrors tokio-modbus::server::service::Service).
• MemoryContext — in-memory Service implementation backed by coil and register maps, useful for tests and examples.
• OptionalService trait — for transports that can selectively drop requests (e.g. RTU unit-id filtering).

#Transport (src/transport/)

• TCP codec: encode_tcp_request, decode_tcp_request, encode_tcp_response, decode_tcp_response, encode_tcp_exception.
• RTU codec: encode_rtu_request, decode_rtu_request, encode_rtu_response, decode_rtu_response, encode_rtu_exception, decode_report_server_id.

#Project structure

modbus-moon/
├── modbus-moon.mbt              # entry point / public API re-exports
├── modbus-moon_test.mbt         # blackbox tests
├── modbus-moon_wbtest.mbt       # whitebox tests
├── pkg.generated.mbti           # generated root interface
├── moon.mod                     # module manifest
├── moon.pkg                     # root package manifest
├── README.md                    # this file (mooncakes.io)
├── LICENSE                      # Apache-2.0
├── AGENTS.md                    # coding conventions
└── src/
    ├── lib/                     # core protocol modules
    │   ├── adu.mbt              # Application Data Unit (TCP / RTU)
    │   ├── coil.mbt             # coil / word bit-packing helpers
    │   ├── constructors.mbt     # cross-package Request/Response ctors
    │   ├── crc.mbt              # Modbus RTU CRC-16
    │   ├── exception.mbt        # ExceptionCode, ExceptionResponse
    │   ├── exception_ctors.mbt  # cross-package ExceptionCode ctors
    │   ├── func_codes.mbt       # FunctionCode enum + byte mapping
    │   ├── function_code_ctors.mbt
    │   ├── pdu.mbt              # Protocol Data Unit (function code + data)
    │   ├── request.mbt          # Request enum + PDU codec
    │   ├── response.mbt         # Response enum + PDU codec
    │   ├── slave.mbt            # Slave / unit id + SlaveContext
    │   └── types.mbt            # ModbusError, ModbusResult
    ├── transport/               # TCP / RTU ADU codecs
    │   ├── tcp.mbt              # MBAP request/response (de)serialization
    │   └── rtu.mbt              # RTU request/response (de)serialization
    ├── client/                  # Modbus client
    │   ├── context.mbt          # Context[R : Runtime], ClientResult
    │   └── traits.mbt           # Reader, Writer + Context impls
    ├── server/                  # Modbus server
    │   ├── service.mbt          # Service, OptionalService traits
    │   └── context.mbt          # MemoryContext + Terminated
    ├── tests/                   # integration tests
    │   └── lib_test.mbt         # codec + server integration tests
    └── examples/                # runnable examples (codec / mock client / sim serial)
    docs/                      # 19-chapter Chinese tutorial

#Quick start

// Encode a request into a PDU
let req = @lib.Request::read_holding_registers(0, 4)
let pdu = req.to_pdu()  // [0x03, 0x00, 0x00, 0x00, 0x04]

// Decode a response
let resp = @lib.Response::read_holding_registers([0x1234, 0x5678])
let resp_pdu = resp.to_pdu()
let parsed = @lib.Response::from_pdu(resp_pdu)
// parsed is `Some(@lib.Response::ReadHoldingRegisters([0x1234, 0x5678]))`

// Encode a TCP request frame
let frame = @transport.encode_tcp_request(@lib.Slave::new(1), req)

// Encode an RTU request frame with CRC
let rtu = @transport.encode_rtu_request(@lib.Slave::new(1), req)

#Status

#Documentation

#Requirements

• MoonBit toolchain (moon)
• Linux / macOS — the moonbitlang/async dependency supports only the native/LLVM backend

#Building & testing

# typecheck the entire workspace
moon check

# run all tests (currently 7 in src/tests/lib_test.mbt)
moon test

# refresh generated interface files and re-format
moon info
moon fmt

#Architecture

#Contributing

#License