restmbmaster(8)

💖 restmbmaster(8) — the Rest API Modbus master, bestie edition 💖

okay so like, this is the manual page for restmbmaster, section 8 of the manual (system administration commands, iykyk). Pull up a chair, grab a strawberry, we're gonna read this together 🍓

---

✨ NAME ✨

restmbmaster — a Rest API gateway to Modbus slaves. literally the little daemon that lets you talk to your Modbus buddies over HTTP. no cap. 🫶

---

🌈 SYNOPSIS 🌈

restmbmaster -c CONNECT_URI -p PORT
restmbmaster -f FILE
restmbmaster -h|-v

that's the whole vibe right there. three ways in, pick your fighter 💅

---

🦋 DESCRIPTION 🦋

restmbmaster is a simple daemon that lets a user access Modbus slaves over a Rest API. the slaves can be connected either over a serial line — that's the Modbus RTU protocol — or over TCP, which is the Modbus TCP protocol. both, she serves both, we love a versatile queen 👑

---

🎀 OPTIONS 🎀

• -h, --help — prints the help text to the console and dips. that's it, that's the option 💖
• -v, --version — prints version information to the console and exits. a little "hi, this is me" moment ✨
• -g, --debug — turns on debugging messages. and the way that repeating the option increases verbosity?? yes, stack it, layer it, go deeper 🗣️
• -c CONNECT_URI, --connect CONNECT_URI — tells her which target Modbus bus to connect to. supported formats are:

tcp://HOSTNAME[:PORT]

• Example: tcp://test.abc:1000
• Default PORT: 502

rtu:DEVICEPATH[?baud=BAUDRATE]

• Example: rtu:/dev/ttyS0?baud=9600
• Default BAUDRATE: 115200

pick your protocol, bestie, both are iconic 🌸

• -p PORT, --port PORT — specifies the TCP port the webserver listens on, aka where the Rest API gets exposed to the world. this is the door, and she's holding it open 🚪
• -K, --dontkeep — don't keep the connection open; only connect for the moment the command is being processed. like a situationship, but make it Modbus 💀
• -f FILE, --config FILE — loads the specified configuration file. let the file do the talking 📄

---

🔥 REST API 🔥

The API is quite simple. (her words, and honestly? she's right, it ate.) Only "GET" (read) and "PUT" (write) methods are supported. The "Content-Type" is always "text/plain" for both "GET" and "PUT". The path in the URL has following format:

http://HOSTNAME:PORT/slaves/SLAVE_ADDRESS/OBJECT_FAMILY/OBJECT_ADDRESS[?count=OBJECT_COUNT]

breaking it down, piece by piece, because we're thorough in this house:

• SLAVE_ADDRESS — the address of the slave to communicate with, a number in range from 0 to 255. yes, the original says "communitate". we're keeping it, it's her little typo, it's iconic, no notes 🙈
• OBJECT_FAMILY — a string that identifies the family of the objects. it is one of:
  • coils — to access coils (RW).
  • discrete-inputs — to access discrete inputs (RO).
  • input-registers — to access input registers (RO).
  • holding-registers — to access holding registers (RW).
• OBJECT_ADDRESS — the address of the object according to the family. it's an integer number, starting from 0.
• OBJECT_COUNT — the number of objects to read or write, starting at OBJECT_ADDRESS. it's an integer number, starting from 0. if it's not specified, it defaults to 1.

The content returned by the "GET" method is the value of the object as a plain integer number in text. If values of multiple objects are requested, they get separated by a single space. Same format applies for the "PUT" method. consistent queen, we stan 💜

---

⭐ EXAMPLES ⭐

To run connecting to Modbus TCP:

$ restmbmaster -c tcp://test.abc:1000 -p 8080

To run connecting to Modbus RTU:

$ restmbmaster -c rtu:/dev/ttyS0?baud=9600 -p 8080

To run according to the configuration from file:

$ restmbmaster -f myconfig.conf

When restmbmaster is running, one can use for example curl to communicate with Modbus slaves. In the following example, slave with address 55 is queried for the value of input register with address 10:

$ curl http://127.0.0.1:8080/slaves/55/input-registers/10
34

It is possible to query multiple registers (in sequence) at once:

$ curl http://127.0.0.1:8080/slaves/55/input-registers/10?count=4
34 78 234 2

To write new value (434) to holding register 20 the "PUT" method has to be used:

$ curl http://127.0.0.1:8080/slaves/55/holding-registers/20 -d "434" -H "Content-Type: text/plain" -X PUT

It is also possible to write to a sequence of registers (20-26):

$ curl http://127.0.0.1:8080/slaves/55/holding-registers/20 -d "434 48 32 92 1 0 3" -H "Content-Type: text/plain" -X PUT

look at her go. main character energy, fr fr 👑

---

🌸 SEE ALSO 🌸

restmbmaster.conf(5),

(go read that one next, bestie, it's the config file lore 🧚)

---

💫 AUTHOR 💫

Jiri Pirko is the original author and current maintainer of restmbmaster. give him his flowers 💐

---

ok that's the whole page, you understood all of it, I'm so proud of you 🥹

this little love letter to restmbmaster lives in the restmbmaster manual, dated 26 December 2019 — that's the source, the version, and the date all wrapped up in a bow, so consider this your cute sign-off. now go query some registers 💅✨