Getting Started with DT-R00x Relay Boards

The goal is simple: drive a Dingtian DT-R00x network relay board over plain HTTP. The board speaks several protocols (Dingtian string/binary, HTTP CGI, Modbus, MQTT, CoAP), but this guide uses the HTTP GET CGI protocol. It is the easiest one to drive by hand, and it is what the Labgrid backend mostly speaks with.

Two endpoints do everything: one reads the state of all relays, one sets a single relay. Once you can reach both from curl, everything else is just choosing the right relay index.

1. Understand the Hardware

The DT-R00x is a family of Ethernet relay boards with 2, 4, 8, 16, 24, or 32 channels. Factory defaults from the User Manual are:

The examples below use 192.168.1.100. Adjust the IP for your own board.

2. Bring the Board Up

Follow this order the first time:

1. Power the board and connect it to your network.
2. Reach the web UI at http://192.168.1.100/. If the board is on a different subnet, temporarily set your machine to 192.168.1.x first.
3. In the web UI, go to “Setting → Relay Connect” and enable the “HTTP GET CGI” protocol for the relay channel.
4. Set a static IP under the Ethernet settings so the board keeps a predictable address. This may need some coordination with IT, but for now DHCP can also work, until we bring Labgrid up for it.
5. Leave the CGI password disabled (pwd=0). The Labgrid backend always sends pwd=0; it does not support an authenticated CGI password.

The most important rule is this: enable “HTTP GET CGI” in step 3. If that protocol is off, every CGI call below fails with a redirect instead of relay state.

3. Confirm the Board Answers

Read the current relay state:

curl "http://192.168.1.100/relay_cgi_load.cgi"

You should get a response like:

&0&4&0&0&0&0&

If you get this, the board is reachable and the CGI protocol is enabled. If you get &302&/& instead, go back and enable “HTTP GET CGI” in the web UI.

4. Read Relay State

The read endpoint is relay_cgi_load.cgi. Its response is &-delimited:

&<result>&<count>&<relay1>&<relay2>&...&<relayN>&

• <result> — 0 = OK, anything else = failure
• <count> — number of relays (2/4/8/16/24/32)
• <relayK> — 0 = OFF, 1 = ON

Example, a 4-channel board with relay 3 ON:

&0&4&0&0&1&0&
        ^ relay 3 = ON

5. Set a Single Relay

The write endpoint is relay_cgi.cgi. It takes the relay as a 0-based index, so channel N is relay index N − 1.

# Turn relay 1 ON   (CGI relay index = 0)
curl "http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=1&time=0&pwd=0&"

# Turn relay 1 OFF
curl "http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=0&time=0&pwd=0&"

# Turn relay 4 ON   (CGI relay index = 3)
curl "http://192.168.1.100/relay_cgi.cgi?type=0&relay=3&on=1&time=0&pwd=0&"

The query parameters are:

6. Read the Write Response

The write endpoint answers in the same &-delimited style:

&<result>&<type>&<relay>&<on>&<time>&

Example, relay 4 set ON succeeds:

&0&0&3&1&0&
   |  |  ^ on = 1  → relay is now ON
   |  ^ relay index 3 (channel 4)
   ^ result 0 = OK

A failure, for example the CGI protocol not enabled or a bad session, looks like:

&302&/&

7. Drive It from Python

The same URLs work pasted into a browser address bar, or from a script. For anything automated I use requests:

import requests

# read state
print(requests.get("http://192.168.1.100/relay_cgi_load.cgi", timeout=5).text)

# relay 2 ON  (channel 2 -> CGI relay=1)
requests.get(
    "http://192.168.1.100/relay_cgi.cgi?type=0&relay=1&on=1&time=0&pwd=0&",
    timeout=5,
)

The only thing worth wrapping in your own helper is the channel-to-index conversion, so you can call set_relay(channel=4, on=True) and let the helper send relay=3.

8. A Practical Bring-Up Sequence

When I bring up a new DT-R00x board, I follow this order:

1. Reach the web UI and enable “HTTP GET CGI”.
2. Set a static IP (or leave DHCP for now).
3. Confirm relay_cgi_load.cgi returns relay state, not &302&/&.
4. Set one relay ON and read it back to confirm the state changed.
5. Wire the Labgrid backend against the same IP with pwd=0.

This order keeps failure analysis simple. If a set command fails, you already know the board is reachable and the CGI protocol is enabled.

References

• Dingtian 4-channel relay product page
• Dingtian relay SDK (manuals and programming examples)