MolSmart API Reference

Relay Boards — API

TCP string protocol, HTTP GET (CGI) endpoints and integration notes for the MolSmart Relay Board family — 2, 4, 8, 16 and 32 channels.

MS-B002MS-B004MS-B008MS-B016MS-B032

ProtocolsTCP · HTTP GET (CGI) · UDP · MQTT

Default TCP port502 (changeable)

Firmware familyRelay-Xch

Source doc versionv1.9.8 (vendor API doc)

1.1 / Getting Started

Overview

Every MolSmart Relay Board (2 through 32 channels) exposes the same open control surface over the local network: a raw TCP string protocol, an HTTP GET CGI interface, an optional UDP socket, and MQTT — so any hub, driver or custom script can turn relays on/off and read their state without a MolSmart cloud account.

Transport	Notes
TCP	Default port 502 (changeable on the module's Integrations/Ports page). Supports both TCP client and TCP server modes.
HTTP	The module runs as its own HTTP server; GET requests only, no request body.
UDP	UDP1/UDP2 sockets carrying the MolSmart binary protocol — used mainly for module‑to‑module and controller polling. Frame format is not covered by the vendor API document this reference is built from; see the To be confirmed note in §1.6.
MQTT	Broker address, topics and QoS are configured per‑module on the web interface's Integrations/Ports page — the module is an MQTT client, never a broker.

Note

Port numbers, MQTT broker/credentials, HTTP Auth and CORS are all set per‑unit on the module's own Integrations/Ports page (web UI) — see this product's User Manual for the full field reference of that page before wiring up an integration.

1.2 / TCP String Protocol

Query Status / KeepAlive

Open a plain TCP connection to the module (default port 502) and send the 2‑character command code below as a raw text string — no line terminator is required.

Command code	Meaning
00	Query status — returns the full relay + input state string described below.

Response format (as documented by the vendor)

[relay1][relay2]...[relayN] : [input1][input2]...[inputN] : [channel count] : last_updates_done_in_last_command_sent : [relay1][relay2]...[relayN] : [input1][input2]...[inputN]

To be confirmed

The response repeats the relay/input block twice, separated by the last_updates_done_in_last_command_sent field — reproduced here exactly as it appears in the vendor document; the meaning of the duplicated second block was not independently re‑verified against a live unit.

Example — 4‑channel board

0000:1111:4:0000:0000

Example — 8‑channel board

00000000:11111111:8:00000000:00000000

Example — 16‑channel board

0000000000000000:1111111111111111:16:0000000000000000:0000000000000000

Example — 32‑channel board

00000000000000000000000000000000:11111111111111111111111111111111:32:00000000000000000000000000000000:00000000000000000000000000000000

1.3 / TCP String Protocol

Control Command

A control command is built by concatenating up to four fields: X + R + C + P. Send it as plain text on the same TCP connection — again, no return/newline is required.

Field	Values
X — action	1 = ON · 2 = OFF
R — relay	1–32 = a single relay · X = all relays
C — command type	omitted = plain ON/OFF · : = Delay · * = Jogging
P — parameter	value required by the C type selected (see the HTTP CGI examples in §1.4 for concrete delay/jogging timings)

11 → relay 1 ON21 → relay 1 OFF13 → relay 3 ON23 → relay 3 OFF132 → relay 32 ON232 → relay 32 OFF1X → all relays ON2X → all relays OFF

To be confirmed

The vendor document only shows worked examples for plain ON/OFF over raw TCP. The : (Delay) and * (Jogging) command types are listed in the field table above but their exact TCP string syntax is not spelled out — the same Delay/Jogging behaviour is documented with concrete parameters via the HTTP CGI endpoint below (§1.4, type=1/type=2).

1.4 / HTTP API (CGI)

Load Relay Status

The board runs as an HTTP server and accepts plain HTTP GET requests — no authentication parameters are shown in the vendor examples below, but see the note on HTTP Auth in §1.6. The CGI file suffix is interchangeable — .cgi, .php and .cs all work.

GET/relay_cgi_load.cgi

Field	Value	Meaning
result	0	0 = ok, any other value = fail
relay count	2 / 4 / 8 / 16 / 24 / 32	number of channels on this board
relay 1…32 status	0 / 1	0 = off, 1 = on (only as many fields as relay count are returned)

Request

http://192.168.1.100/relay_cgi_load.cgi

Response — ok, 4-channel board, relay1 on / relay2 off / relay3 on / relay4 off

&0&4&1&0&1&0&

1.5 / HTTP API (CGI)

Set Relay

GET/relay_cgi.cgi

Parameter	Values	Meaning
type	0 / 1 / 2	0 = on/off · 1 = jogging · 2 = delay
relay	0–31	0 = relay 1, 1 = relay 2, … 31 = relay 32
on	0 / 1	0 = off, 1 = on
time	0 · 1–255 · 1–65535	meaning depends on type — see below
pwd	0–9999	password configured on the device (Relay Password on Integrations/Ports); 0 disables the check

Type	Time field meaning
type=0 (on/off)	time is ignored (send 0)
type=1 (jogging)	time in units of 100 ms, range 1–255 (e.g. 5 = 500 ms)
type=2 (delay)	time in whole seconds, range 1–65535

Response mirrors the request fields: result, type, relay, on, time.

Example 1 — relay 1 ON

http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=1&time=0&pwd=0&

Response

&0&0&0&1&0&

Example 2 — relay 1 OFF

http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=0&time=0&pwd=0&

Response

&0&0&0&0&0&

Example 3 — relay 2 jogging ON, 500 ms

http://192.168.1.100/relay_cgi.cgi?type=1&relay=1&on=1&time=5&pwd=4660&

Response

&0&1&1&1&5&

Example 4 — relay 2 jogging OFF, 500 ms

http://192.168.1.100/relay_cgi.cgi?type=1&relay=1&on=0&time=5&pwd=4660&

Response

&0&1&1&0&5&

Example 5 — relay 2 ON, delayed OFF after 10 s

http://192.168.1.100/relay_cgi.cgi?type=2&relay=1&on=1&time=10&pwd=4660&

Response

&0&2&1&1&10&

Example 6 — relay 2 OFF, delayed ON after 10 s

http://192.168.1.100/relay_cgi.cgi?type=2&relay=1&on=0&time=10&pwd=4660&

Response

&0&2&1&0&10&

1.6 / HTTP API (CGI)

Load Input Status

GET/input.cgi

Field	Value	Meaning
result	0	0 = ok, any other value = fail
input start position	0	default 0
input count	2 / 4 / 8 / 16 / 24 / 32	number of digital inputs on this board
input 1…32 status	0 / 1	0 = low, 1 = high

Request

http://192.168.1.100/input.cgi

Response — ok, 4 inputs: input1 high / input2 low / input3 high / input4 low

&0&0&4&1&0&1&0&

1.7 / MQTT

Topics & Payloads

To be confirmed

The vendor API document reviewed for the Relay Board family does not list explicit MQTT topic names, unlike the Dimmer TRIAC and Dimmer 0‑10V documents (which do — see those pages). Relay Boards share the same MQTT configuration block (broker address, QoS, Retain, HA Discover, etc. — Integrations/Ports > MQTT) and are very likely to follow the same /molsmart/<device><serial>/in/… topic shape used by the Dimmer family, but this has not been independently confirmed for Relay Boards. Verify the exact topic names against a live unit (e.g. with MQTT Explorer) before building an integration on this channel.

1.8 / Reference

Notes & Open Items

Open item	Detail
UDP1/UDP2 frame format	Referenced generically as 'the MolSmart binary protocol' on Integrations/Ports; the exact byte layout is not covered by the source document used for this reference.
HTTP Auth / Session ID	The web UI exposes an HTTP Auth toggle and a magic Session‑ID token for scripted access (see the product's User Manual, Config page) — whether/how it gates the CGI endpoints above (beyond the pwd parameter on relay_cgi.cgi) was not confirmed in the source reviewed.
API doc revision	The vendor document used for this page is tagged V1.9.8 — later firmware may extend or change these endpoints.

For the full field reference of the web interface pages these protocols draw from (Integrations/Ports, Config, MQTT, etc.), see this product's User Manual.