MojoScale Studio Docs
API Reference

modbus

Industrial Modbus native Berry module.

All modules Open Studio
Studio Docs Buses & Protocols

import modbus

The modbus module provides profile-driven synchronous Modbus RTU reads. A profile is a JSON string that describes named registers, coils, scaling, units, and writes. After the profile is loaded, scripts work with names such as ``modbus.get("temperature")`` instead of hand-reading register addresses. Use ``system.schedule`` when a profile value should be read periodically.

Quick example

import modbus
import system

profile = '''
{
  "slave": 1,
  "entries": [
    {"name": "temperature", "function": "input", "address": 0, "type": "int", "scale": 0.1, "unit": "C"},
    {"name": "run_command", "function_codes": [3, 6], "address": 10, "type": "uint", "access": "read/write"}
  ]
}
'''

modbus.begin(baud=9600, tx=17, rx=16)
modbus.load_profile(profile)

def read_temperature():
    print(modbus.get("temperature"))

system.schedule("temperature", 5000, 5000, -1, read_temperature)

importmodbus

Industrial Modbus native Berry module.

The modbus module provides profile-driven synchronous Modbus RTU reads. A profile is a JSON string that describes named registers, coils, scaling, units, and writes. After the profile is loaded, scripts work with names such as ``modbus.get("temperature")`` instead of hand-reading register addresses. Use ``system.schedule`` when a profile value should be read periodically.

API 9 available

modbus.begin(baud: int, tx: int, rx: int, de: int = None, uart: int = None, timeout_ms: int = None, retries: any = None, delay_ms: int = None, offset: float = None) -> bool

Initialize Modbus RTU on a UART bus.

Parameters
Name Type Pass as Required Description
baud int positional or keyword Yes Serial baud rate, such as 9600 or 19200.
tx int positional or keyword Yes GPIO pin used for UART transmit.
rx int positional or keyword Yes GPIO pin used for UART receive.
de int positional or keyword No Optional RS485 driver-enable GPIO pin. Defaults to no DE pin.
uart int positional or keyword No Optional ESP-IDF UART number. Defaults to UART1.
timeout_ms int positional or keyword No Optional response timeout in milliseconds.
retries any positional or keyword No Optional number of retry attempts per request.
delay_ms int positional or keyword No Optional delay between profile reads in milliseconds.
offset float positional or keyword No Optional register address offset applied to all reads and writes.
Returns

bool True when the UART configuration is accepted.

modbus.load_profile(profile: str) -> bool

Load a JSON Modbus profile.

The JSON may use an ``entries`` array, a ``registers`` array, or a register-reference object such as ``{"30001": {"name": "temperature"}}``. Entry names are normalized to lowercase snake_case.

Parameters
Name Type Pass as Required Description
profile str positional or keyword Yes JSON string containing the Modbus profile.
Returns

bool True when at least one readable entry is loaded.

modbus.get(name: str) -> bool

Synchronously read and return one named profile entry.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Profile entry name, such as "temperature".
Returns

bool Bool, int, or float value from the current Modbus read. Returns None when the name is missing or the read fails.

modbus.get_all() -> dict

Synchronously read and return all profile values.

Returns

dict Map of profile entry names to bool, int, or float values from the current Modbus reads.

modbus.info(name: str) -> dict

Return status metadata for one profile entry.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Profile entry name.
Returns

dict Map containing found, name, value, unit, type, slave, function, address, count, valid, writable, age_ms, and last_error.

modbus.write(name: str, value: any = None) -> bool

Write one named profile entry.

If the profile entry includes a fixed write value, the value argument can be omitted. Otherwise pass the value to write.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Writable profile entry name.
value any positional or keyword No Optional value to write. Required unless the profile entry defines ``value`` or ``write_value``.
Returns

bool True when the Modbus write request succeeds.

modbus.status() -> dict

Return module and profile status.

Returns

dict Map containing loaded, mode, entries, success, failed, timeout_ms, retries, and last_error.

modbus.read_raw(slave: any, function: any, address: int, count: int) -> list

Read a raw Modbus address range.

Parameters
Name Type Pass as Required Description
slave any positional or keyword Yes Modbus slave id.
function any positional or keyword Yes Read function code: 1 coils, 2 discrete inputs, 3 holding registers, or 4 input registers.
address int positional or keyword Yes Zero-based register or coil address.
count int positional or keyword Yes Number of values to read.
Returns

list List of booleans for function 1 or 2, or register integers for function 3 or 4. Returns None when the request fails.

modbus.write_raw(slave: any, function: any, address: int, value: list) -> bool

Write a raw Modbus value.

Parameters
Name Type Pass as Required Description
slave any positional or keyword Yes Modbus slave id.
function any positional or keyword Yes Write function code: 5 coil, 6 single register, or 16 multiple registers.
address int positional or keyword Yes Zero-based register or coil address.
value list positional or keyword Yes Boolean, integer, or list of register integers to write.
Returns

bool True when the Modbus write request succeeds.