WB-MGE v.3 Interface Converter (RS-485, Ethernet, Wi-Fi, WBIO)
This page describes the new device WB-MGE v.3, the description of the previous version is WB-MGE v.2.
This page describes the latest revision of the device with the latest stable firmware. If the firmware of your device is old, update it if possible (see Firmware update).
Designed for connecting devices with an RS-485 interface and WBIO side input/output modules to an automation server via Ethernet or Wi-Fi. The server can be a Wiren Board controller or any controller / computer supporting the required protocols.
Two WB-MGE v.3 units can be used to set up a bridge over Ethernet or Wi-Fi. This is useful when a third-party controller has no network interfaces but a remote RS-485 segment has to be polled.
Each port is assigned a mode: «Modbus TCP», «Transparent bridge» or «Passive». On top of any mode, overlays can be enabled independently — a sniffer of Modbus traffic and a caching multimaster (a Modbus TCP server serving values from the cache). Both ports together can work as a repeater — a transparent RS-485 relay between Port 1 and Port 2.
The device is flashed and ready to use as a gateway. The firmware is open source (MIT-WB license), sources: github.com/wirenboard/wb-mge. You can add any functionality you need for your own tasks or write your own firmware. Read more about developing DIY firmware.
Differences from previous version
Differences between WB-MGE v.3 and WB-MGE v.2:
- a modern multilingual web interface (Russian, English, German, Italian, Kazakh) that works on a computer and on a mobile phone;
- 2 RS485 ports with the ability to use any protocols on each of them;
- in addition to Ethernet there is now Wi-Fi, which can be disabled if it is not needed — including permanently (important for projects where wireless communications are prohibited);
- optional PoE 802.3af, 802.3at via the WBP-ACTIVE-POE module, with the ability to power the devices connected to the WB-MGE v.3;
- support for WBIO side input/output modules;
- electronic control of terminators and failsafe bias;
- power control of connected devices;
- factory mode for restoring operation in case of problems with the main firmware;
- a debug USB-C port;
- a Modbus traffic sniffer with decoding right in the web interface;
- a caching multimaster: the gateway collects values from the bus and serves them over a separate Modbus TCP server without re-polling the devices — several masters can read the data in parallel;
- transmission (TX) disabling on a port — the transceiver is physically switched to receive-only mode for a completely non-invasive connection to existing systems;
- a repeater mode — a transparent RS-485 relay between the two ports;
- open source firmware (MIT-WB license);
- developers can use the module hardware in their own firmware.
Specifications
| Parameter | Value |
|---|---|
| Power supply | |
| Interface power supply voltage | 9 V — 28 V DC |
| Power consumption at 24 V | 1 W |
| Maximum current from Vout | 2.5 A |
| Maximum current from Vout when powered by PoE (continuous) | 500 mA |
| Power inputs |
|
| Power input priority |
from the input with the higher voltage |
| Output for powering external devices | |
| Vout | Module power supply voltage is supplied to the terminals, with overcurrent protection above 2.5 A, software shutdown and state retention across reboots.
When powered by PoE, a stabilized 24 V voltage is supplied to Vout. When powered by PoE, the current drawn from Vout is lower. |
| Terminal blocks and wire cross-section | |
| Recommended wire cross-section with a sleeve terminal | 0.35 – 1 mm2 — single, 0.35 – 0.5 mm2 – double crimping |
| Length of a standard sleeve terminal | 8 mm |
| Screw tightening torque | 0.2 N∙m |
| Communication | |
| Data exchange protocol |
Via RS-485 terminals:
Side I/O connector: WBIO. |
| Interfaces |
|
| RS-485 interface parameters | Set in software, by default:
speed 9600 bps; data — 8 bits; parity N; stop bits 2 |
| Ready for operation after power-up | 8 s |
| Operating conditions | |
| Air temperature | −40 to +70 °C |
| Relative humidity | Up to 95 %, non-condensing |
| Climatic execution according to GOST 15150-69 | O2.1* |
| Warranty period | 2 years |
| Service life | 5 years |
| Dimensions | |
| Width, DIN units | 2 |
| Overall dimensions (L x W x H) | 36 x 90 x 58 mm |
| Weight (with packaging) |
105 g |
General principle of operation
Hardware
The module is based on the ESP32 chip, which implements the functions of an RS-485 gateway, allows controlling peripherals and indicators, and provides a web interface and API for configuring the module.
Network interfaces and packet handling
The module has two network interfaces: Ethernet and Wi-Fi, which can act as an access point or a client.
The module firmware receives packets over Ethernet / Wi-Fi and sends them to one of the RS-485 ports, then relays the device responses back. The port is selected by the TCP port the packet arrived on, by default: 502 — RS485-1, 503 — RS485-2.
Besides pass-through forwarding, two independent tools that work passively with the bus traffic can be enabled on top of any port:
- sniffer — captures and decodes Modbus frames in both directions and shows them in real time in the web interface (diagnosing the exchange without an external analyzer);
- caching multimaster — collects the latest device register values from the traffic and serves them over a separate Modbus TCP server without re-polling the bus, removing the «one master per line» restriction.
Both are described in detail in the Operating modes section.
Working with WBIO
To connect WBIO side modules, there is an additional WB-MIO inside, which presents all side modules as a single Modbus device on the RS-485-2 port. Read about addressing and configuration in the configuration section: I/O Bus (WBIO side modules).
Fast Modbus
The specific feature of Fast Modbus is the presence of arbitration packets:
- Transparent mode — we pass the packets through as is;
- Modbus TCP — we handle the arbitration packets separately in the gateway firmware.
As a result, Fast Modbus works in both modes.
Power supply
The module can be powered in two ways: directly from the Vin terminal or, optionally, over PoE conforming to the IEEE 802.3af / 802.3at standards.
Powering over PoE requires a separate WBP-ACTIVE-POE module with a built-in voltage converter, which is installed inside the device. It converts the incoming PoE voltage to 24 V and supplies it to the internal power bus of the gateway.
The WBP-PASSIVE-POE module may be used, but only at a supply voltage no higher than 24 V DC. Exceeding this voltage will damage the gateway.
The module has two power outputs (Vout) for connecting peripheral devices. The outputs are controlled as a group: both channels are switched on and off simultaneously via the web interface. The total load on both outputs must not exceed the value given in the table.
| Connected load power | Vin (24 V) | Active PoE mode | Passive PoE mode | |
|---|---|---|---|---|
| 802.3af | 802.3at | |||
| Nominal | 60 W | 15 W | ||
| Maximum short-term | 120 W | 12 W | 28 W | 30 W |
Indication
On the front panel, under the label, there are indicators that show the state of the module and its outputs.
| Designation | Color | State | Meaning |
|---|---|---|---|
| Status | Green | blinking | the device has booted and is operating normally |
| on | power is present, problem with the firmware | ||
| Vout | Orange | on | device power ON |
| off | device power OFF | ||
| Ethernet | Green | on | link present |
| blinking | data exchange in progress | ||
| off | no link | ||
| Wi-Fi | Green | on | enabled, no data exchange |
| blinking | data exchange in progress | ||
| off | disabled | ||
| RS485 1/2 | Green (RX) | blinking | receiving data from the port |
| Orange (TX) | blinking | sending data to the port |
Installation
The WB-MGE v.3 is mounted on a standard 35 mm wide DIN rail and occupies the width of 2 DIN modules.
Connecting wires
We recommend using flexible multi-strand wires with the ends crimped using sleeve terminals.
When stripping the insulation, the wire should be stripped exactly to the length of the sleeve (you can strip more and then cut off the protruding excess). For crimping, use crimping pliers (crimper). During installation, the wire crimped with a terminal is not damaged by the screw clamp and is securely fastened.
Do not apply excessive force when tightening the terminal—this will damage the screw connection.
Module power supply
The V+ GND terminal block with a 5.08 mm pitch is used to connect the power supply.
The module can also be powered over Ethernet PoE.
Network interfaces
The module is connected to a Wiren Board controller or another device directly over Ethernet or via Wi-Fi, including through a router or a VPN. The main requirement is that the IP address of the module must be reachable from the controller.
RS-485
The V+ GND A B terminal block with a 3.5 mm pitch is used to connect devices over the RS-485 bus. Power for the connected devices can also be taken from these terminals. For a stable connection with a device it is important to wire the RS-485 bus correctly, read about it in the article RS-485 bus physical connection.
The RS-485 interfaces are independent, each has individual settings for speed, stop bits and other parameters. The terminator and failsafe bias are enabled by default. They can be disabled in the settings. The RS-485 grounds in the WB-MGE v.3 are not isolated from the power ground.
I/O Bus
Up to 8 modules can be connected in series: up to 4 input modules (type «I») and up to 4 output modules (type «O»).
WBIO side input/output modules are connected to the I/O Bus port located on the right side of the module. Make sure that all pins of the module fit into the holes of the mating connector.
The device makes it possible to separate the input/output modules from the Wiren Board controller and move them to another DIN rail or another cabinet. In addition, this interface converter allows using the input/output modules as a standalone device with controllers from other manufacturers.
- Connecting devices to the WB-MGE v.3
Side modules
A side module and RS-485 devices at the same time
Operating modes
«Modbus TCP» mode
In this mode the module receives Modbus TCP requests over the network interfaces, converts them into Modbus RTU and passes them to one of the RS-485 ports. The received RTU response is converted back into Modbus TCP and returned to the client that sent the request.
The mode is selected for each port separately:
- Go to Modbus Tools → TCP gateway and select the card of the required port.
- In the Mode field select «Modbus TCP».
- If necessary, specify the TCP port whose requests will be forwarded to this RS-485 port.
In Modbus TCP mode the module works only as a server. Several TCP clients (up to 8) can be connected to each port at the same time.
«Transparent gateway» mode
In this mode the module receives, over the network interfaces, TCP packets with data of any protocol (for example, Modbus RTU over TCP) and passes them byte for byte to one of the RS-485 ports. The received response is likewise passed back unchanged to the client the request came from.
The mode is selected for each port separately:
- Go to Modbus Tools → TCP gateway and select the card of the required port.
- In the Mode field select «Transparent bridge» and set the role in the Role field.
- If necessary, specify the TCP port whose requests will be forwarded to this RS-485 port.
The following roles are available in the «Transparent bridge» mode:
- Server — used when, for example, a Wiren Board controller connects to it.
- Client — used when the WB-MGE v.3 connects to another module of the same kind.
In this mode only one master is allowed on each port.
Sniffer
Available since firmware version 1.3.0
The sniffer captures traffic on the selected RS-485 port in both directions, decodes Modbus frames (including Fast Modbus) and displays them in real time in the web interface over WebSocket. Convenient for diagnosing the exchange without an external analyzer.
Open Modbus Tools → Sniffer, select a port and click Start. For each frame the following is shown: the sender (master/slave), the device address, the function code, the data (HEX), the length and the CRC check result. Available:
- filters by Slave ID and function code, packet and CRC error counters;
- the Send packet button — compose and send a read (FC01–FC04) or write (FC05/06/15/16) request to the bus; the CRC is calculated automatically, a frame preview is shown;
- export of the captured packets to CSV.
The sniffer is an overlay on top of an already open port: it does not switch the transport mode and works in parallel with the cache.
Caching multimaster
Available since firmware version 1.3.0
The gateway can passively monitor the Modbus exchange on the bus, remember the latest register and bit values of all devices and serve them over a separate Modbus TCP server (port 504 by default) — without re-polling the devices. This removes the «one master per bus» restriction: the real masters keep polling, while additional TCP clients read the data from the cache.
Open Modbus Tools → Register map and turn on the Caching toggle. On the page:
- the automatically collected map (device → register type → register) and statistics (number of devices, processed packets, map age, memory usage);
- Value timeout — after how many seconds a value in the cache is considered stale. If at the moment of the request the value has not been updated for longer than the timeout, the cache returns not the old number but the Modbus exception 0x0B («gateway target device failed to respond»); 0 disables the check. See below for details;
- Listening port — the source port for the cache; TCP port — the port of the cache Modbus TCP server (504 by default);
- export of the map to CSV/JSON and resetting the map.
How the value timeout works. Every value in the cache has an age counter: it is reset on every new device response on the bus and grows by 1 second per second. On a Modbus TCP request the cache compares the age with the timeout:
- age ≤ timeout — the cached value is served;
- age > timeout — the 0x0B exception is returned instead of the value. This is how the client tells live data from «frozen» data: if a device has disappeared from the bus, its registers start returning an error rather than the last remembered value. When reading a range in a single request, one stale value is enough for the whole response to become the 0x0B exception (a register missing from the cache gives the 0x02 exception).
The age counter is capped and stops at 65535 seconds (≈18.2 hours) — this is also the maximum allowed timeout. Therefore the «shelf life» of a value cannot be set longer than ~18 hours. A special case is a timeout set to the maximum (65535): the age never exceeds this threshold, so the value is never marked stale at all and the check effectively does not fire — the same as with the value 0.
The cache is an independent overlay: it can be enabled on a port in any transport mode (enabling it on a disabled port opens the port in «Passive (listening)» mode).
The gateway's own register map (Unit ID 255)
Available since firmware version 1.3.0 The gateway responds over TCP-Modbus to a request addressed to its own Unit ID 255 (0xFF) — this address is reserved for the TCP gateway. It works in the «Modbus TCP» and «Cache TCP» modes regardless of the cache state (in Modbus TCP mode such a request is not forwarded to RS-485).
There is a single address space. The FC03 (holding) and FC04 (input) functions serve a common map: any address from the table below returns the same value on both functions. In the common Wiren Board register map the fields are formally listed either as input or as holding, but the reference firmware responds with the whole map on both functions, and the standard utilities rely on this: wb-mcu-fw-flasher --get-device-info and modbus_client -t3 -r <address> read the signature and the info block over FC03, while pollers use FC04.
| Address (dec) | Address (hex) | Registers | Type | Description |
|---|---|---|---|---|
| 104–105 | 0x0068–0x0069 | 2 | u32 | Uptime since boot, seconds |
| 121 | 0x0079 | 1 | u16 | Current supply voltage, mV |
| 200–219 | 0x00C8–0x00DB | 20 | string (1 char/reg) | Device model |
| 220–244 | 0x00DC–0x00F4 | 25 | string (2 chars/reg) | Commit hash and the branch the firmware was built from |
| 250–265 | 0x00FA–0x0109 | 16 | string (1 char/reg) | Firmware version (as a string) |
| 266–269 | 0x010A–0x010D | 4 | u64 | Serial number extension |
| 270–271 | 0x010E–0x010F | 2 | u32 | Serial number |
| 290–301 | 0x0122–0x012D | 12 | string (1 char/reg) | Firmware signature |
| 320 | 0x0140 | 1 | u16 | Firmware version: MAJOR |
| 321 | 0x0141 | 1 | u16 | Firmware version: MINOR |
| 322 | 0x0142 | 1 | u16 | Firmware version: PATCH |
| 323 | 0x0143 | 1 | s16 | Firmware version: SUFFIX (+N for +wbN, −N for -rcN, 0 if none) |
| 324–325 | 0x0144–0x0145 | 2 | u32 | Version in numeric format (word order little-endian: 324 — low word) |
| 326–327 | 0x0146–0x0147 | 2 | u32 | Version in numeric format (word order big-endian: 326 — high word) |
| 330–337 (0x014A–0x0151) — the bootloader version field of the common WB map, not defined here (see below) | ||||
| 528–529 | 0x0210–0x0211 | 2 | u32 | Number of processed packets (since the last cache reset) |
| 530–531 | 0x0212–0x0213 | 2 | u32 | Seconds since the last packet on the bus |
| 532 | 0x0214 | 1 | u16 | Number of devices on the bus (unique slave_id values in the cache) |
| 533 | 0x0215 | 1 | u16 | Average bus polling rate, polls/min |
| 534 | 0x0216 | 1 | u16 | Cache value timeout, seconds |
| 65504 | 0xFFE0 | 1 | u16 | Maximum used stack, KB (0 — stack corrupted / unknown) |
| 65505 | 0xFFE1 | 1 | u16 | Amount of free RAM, KB |
| 65506 | 0xFFE2 | 1 | u16 | Amount of used RAM, KB |
| 65507 | 0xFFE3 | 1 | u16 | Stack size, KB |
| 65508 | 0xFFE4 | 1 | u16 | Reason for the last MCU reboot |
Notes on the register map:
- String packing differs between fields — this is dictated by the common Wiren Board register map, otherwise the standard utilities read garbage:
- 1 character per register, the character in the low byte (the high one is 0x00): model (200–219), firmware version (250–265), signature (290–301). The sign of this layout is that the number of registers equals the number of characters. The standard calls
modbus_client -t3 -r 290 -c 12 | sed 's/ 0x00/\x/g'andwb-mcu-fw-flasher --get-device-inforely on it; - 2 characters per register, the first character of the pair is in the low byte, the second in the high one: git info (220–244, 25 registers = 50 characters).
- The tail of a field is padded with zeros.
- 1 character per register, the character in the low byte (the high one is 0x00): model (200–219), firmware version (250–265), signature (290–301). The sign of this layout is that the number of registers equals the number of characters. The standard calls
- The bootloader zone 330–337. The bootloader version field of the common WB map is read as eight registers starting at address 330 (
modbus_client -t0x03 -r330 -c8), so the whole range is left unoccupied — there are no registers of our own here, all the more so on FC03. For the same reason the statistics block is moved outside the common WB map, to 528–534 — seven consecutive registers are read in a single request. - Multi-register integers (except 324–325) are stored in big-endian word order — the high word at the lower address.
- The numeric version is calculated according to the Wiren Board rule (Modbus-hardware-version):
if (SUFFIX >= 0) enc = SUFFIX + 128; else enc = -1 - SUFFIX;VERSION = (MAJOR << 24) | (MINOR << 16) | (PATCH << 8) | enc. - The reboot reason (65508): 1 — LPWR (brownout/wake from sleep), 2 — WWDG (interrupt watchdog), 3 — IWDG (task/general watchdog), 4 — SFT (software reset/panic), 5 — POR (power-on), 6 — PIN (external reset), 0 — unknown.
- The bus statistics (528–534) are taken from the multimaster cache; when the cache is inactive the corresponding fields read as 0.
- Reading a range where at least one address is undefined returns the 0x02 exception (illegal data address); a function other than FC03/FC04 — the 0x01 exception (illegal function). No more than 125 registers are read in a single request.
Repeater (Serial)
Available since firmware version 1.3.0
The repeater is a transparent «Serial↔Serial» transfer: the bytes received on Port 1 are forwarded byte by byte to Port 2 and vice versa, without parsing frames. It is used to extend an RS-485 line and to restore signal integrity.
Open Modbus Tools → Repeater and click the toggle — it switches both ports into repeater mode (clicking again turns it off). The page shows the forwarding statistics in real time: bytes forwarded in each direction, bytes lost on each port, uptime and average speed.
Bytes lost is the counter of bytes received on a port that could not be forwarded to the opposite port (its transmit buffer is full): the incoming stream briefly exceeded the transmit throughput. In normal operation it is zero.
Different port speeds. The port speeds are independent, and the repeater can work at different speeds, but not always reliably. It works best in the asymmetric case: the master on the slow line (for example, 9600), the slave on the fast one (for example, 115200). Then the master sends requests slowly, and only the responses to its requests are relayed back — there is little oncoming traffic. But even so the line can be overloaded if a very large chunk of data is requested in a single request: the size of one frame is limited by a 1000-byte buffer, and if the slave responds with a packet longer than that, the frame will overflow the buffer and will be dropped already on reception.
Attention: while the repeater is active, both RS-485 segments behave as if electrically connected. If there are masters on both sides of the bus, collisions on the bus and loss of communication are possible. This is a local connection of two ports of one module; joining segments through two modules over IP is described in the section Repeater (two modules over TCP).
Repeater (two modules over TCP)
If you want to join two RS-485 bus segments through a local network or a VPN using WB-MGE v.3 — select the Transparent mode and the Server role for one module, and Transparent and the Client role for the other, and specify the IP address of the server.
Important! This scheme is recommended only if it is not possible to connect the WB-MGE v.3 gateway to the Wiren Board controller directly over Ethernet or Wi-Fi, and it has the following limitations:
- devices with Fast Modbus can only be located in one of the bus segments (how to disable Fast Modbus on a device);
- the delay before sending the next request has to be increased (for a speed of 9600 baud — at least 50 ms). Applicable only if, besides the WB-MGE v.3, slave devices are also connected to the RS-485 bus on the controller side.
When joining two RS-485 bus segments using WB-MGE v.3 gateways and polling the devices from a Wiren Board controller, set the «Response timeout» parameter in the RS-485 port settings of the wb-mqtt-serial driver to at least 200-250 ms when working over Ethernet, or at least 350 ms when working over Wi-Fi or through a VPN.
If there are slave devices on the RS-485 bus on the controller side, it is also necessary to set the «Delay before writing to the port» parameter in the RS-485 port settings of the wb-mqtt-serial driver to at least 50000 µs for a speed of 9600 baud (as the speed increases the value of the parameter can be reduced).
I/O Bus (WBIO side modules)
The side modules work through the built-in WB-MIO, which presents them as a Modbus device on the RS485-2 port with the default settings used on all Wiren Board devices:
- address — 247;
- communication parameters — 9600 8N2.
In the web interface of the module you can enable or disable the built-in WB-MIO, to do this:
- Go to Configuration → Serial ports and find the I/O Bus card.
- Switch Enable I/O Bus to the required state.
The WB-MIO is enabled by default, disable it if you need to free up the Modbus address it occupies or if an arbitrary protocol that conflicts with Modbus RTU is going to be used on the RS485-2 port.
Important! The communication parameter settings of the connected devices and the settings of the built-in WB-MIO must match. If the settings of the connected devices differ, the WB-MIO settings have to be changed by writing new values into the registers. The values can be written:
- in the controller web interface through the settings of the wb-mqtt-serial driver;
- through the SSH console of the controller with the Modbus-client utility, the RS485-2 port must be operating in the «Modbus TCP» mode;
- Stop the wb-mqtt-serial driver:
systemctl stop wb-mqtt-serial
- Write the new value of the WB-MIO RS-485 port speed:
modbus_client --debug -mtcp -a247 -c1 -r110 -t0x06 -o300 -p503 10.42.0.176 1152
- where
247is the WB-MIO address,10.42.0.176is the IP address of the module,1152is the value for the speed of 11520 bps.
- Start the wb-mqtt-serial driver:
systemctl start wb-mqtt-serial
- Stop the wb-mqtt-serial driver:
- by connecting directly to the RS485-2 port through the WB-USB485 interface converter.
| Адрес | Register Options | Description | Values | Примечание | |||
|---|---|---|---|---|---|---|---|
| Dec | Hex | Type | Access | Format | |||
| Параметры подключения | |||||||
| 110 | 0x006E | Holding | RW | u16 | Baud rate of RS-485. Setting connection parameters RS-485 |
x100, Bauds 12 — 1200 bps, 24 — 2400 bps, 48 — 4800 bps, 96 — 9600 bps, 192 — 19 200 bps, 384 — 38 400 bps, 576 — 57 600 bps, 1152 — 115 200 bps |
|
| 111 | 0x006F | Holding | RW | u16 | Parity bit configurating of RS-485 | 0 — no parity bit (none), 1 — odd, 2 — even |
|
| 112 | 0x0070 | Holding | RW | u16 | Number of stop bits | 1, 2 | |
| 128 | 0x0080 | Holding | RW | u16 | Modbus address of the device (more) | ||
Configuration
Web interface
For convenient configuration the module has a web interface that works in modern browsers on a computer and on mobile phones. To access it you need to connect the computer and the module to the same network through one of the interfaces:
- Wi-Fi, where it brings up an access point and automatically assigns IP addresses to the clients.
- Ethernet, here no IP addresses are configured, the module must obtain them over DHCP, for example, from your router.
The default values are given in the table below. Information about the network settings is also printed to the debug console available through the USB-C connector under the cover of the module.
- Web interface screenshots
| General | |
|---|---|
| Login | admin |
| Password | admin |
| mDNS host name | wb-mge-XXXXXX.local, where XXXXXX are the last 3 digits of the Ethernet MAC in hex format
You can also take the name of the access point printed on the label and append .local to it |
| Wi-Fi | |
| Access point | WB-MGE-XXXXXX, where XXXXXX are the last 3 digits of the Ethernet MAC in hex format. |
| Key (password) | printed on the label on the side of the device. |
| IP address | 192.168.5.1 |
| Subnet mask | 255.255.255.0 |
| Ethernet | |
| IP address | DHCP |
| Subnet mask | DHCP |
Accessing the web interface
Via a Wi-Fi access point
By default Wi-Fi works in access point mode:
- Open the list of Wi-Fi access points on your laptop or phone and connect to WB-MGE-XXXXXX, where XXXXXX are the last 3 digits of the Ethernet MAC in hex format.
- Enter the security key (password) printed on the label on the side of the device.
- The web interface will be available at 192.168.5.1, login / password — admin / admin.
Over Ethernet
By default the Ethernet port of the module is configured to obtain an IP address over DHCP, so you will need a router with IP address distribution configured — usually this is any router installed in a flat or an office:
- Connect the module to the router over Ethernet;
- Go to the settings of your router and see which IP address it has assigned to the module.
- Open a web browser on a computer connected to the same router. The web interface will be available at the IP address from the previous step, login / password — admin / admin.
Via the controller Ethernet port
If the module is connected to the Ethernet port of the controller and is on a different subnet, its web interface can be accessed through an SSH tunnel. In the example below you connect from your computer to the controller with the address 192.168.42.1, and the module has the address 192.168.0.7.
- Create an SSH tunnel:
- On Linux/macOS (OpenSSH) or Windows (PowerShell / CMD):
ssh -N -L 8088:192.168.0.7:80 root@192.168.42.1
- When prompted for the password enter — wirenboard (the default password). The -L option forwards the local port 8088 to 192.168.0.7:80 through the controller, -N does not run a remote command. If port 8088 is busy, specify another free local port. Keep the session open while you use the web interface.
- On Windows (PuTTY):
- In Session specify Host Name: 192.168.42.1, then go to Connection → SSH → Tunnels.
- In Source port enter 8088.
- In Destination enter 192.168.0.7:80.
- The tunnel type is Local. Click Add.
- Return to Session, click Open and log in as the user root.
- On Linux/macOS (OpenSSH) or Windows (PowerShell / CMD):
- Open the web interface in a browser at the address, enter the login and the password:
http://127.0.0.1:8088/
Via Wiren Board Cloud
If the WB-MGE v.3 is connected to one of the network interfaces of the controller, and the controller is in Wiren Board Cloud — the web interface of the module can be proxied and accessed through the cloud. Details in Getting access to arbitrary web interfaces on the controller.
Saving and loading configuration
The configured parameters can be saved to a file and used to restore them on a new device or when creating identical installations.
All the settings of the web interface, the ports and the network interfaces are exported to the file.
Terminator and failsafe bias
The module has the following installed and enabled by default:
- terminator — a 120 Ohm resistor connected between lines A and B. If the module is at the end of the bus — it must be enabled, if in the middle — disabled.
- failsafe bias — 560 Ohm resistors that pull the bus apart, eliminating the uncertainty when the device transmitters are off. If the module works as a master — it must be enabled, in all other cases disabled.
The control is done in software: go to Configuration → Serial ports and set the required status in the card of the required port.
Disabling transmission (TX)
Available since firmware version 1.3.0
For each RS-485 port on the Configuration → Serial ports page there is a Disable transmission (TX) toggle. It physically switches the RS-485 transceiver into receive-only mode: the direction control pin (DE) is detached from the UART and held in the inactive state. While the mode is on, it is impossible to send anything to the line even in software — any attempt to transmit is silently discarded.
This makes it possible to safely connect to already operating installations and to analyze or mirror their traffic (with the sniffer or the caching multimaster) without the fear that an accidental transmission will disrupt the system. If a port is switched into receive-only mode, the Send packet button in the sniffer is unavailable.
Permanently disabling Wi-Fi
Available since firmware version 1.3.0 The WB-MGE supports the permanent Wi-Fi disabling mode. After activation the Wi-Fi driver is no longer initialized — the radio module stays off on all subsequent boots, and the Wi-Fi settings section is hidden in the web interface. This mode cannot be undone through the API.
Activation through the API (requires a reboot to take effect):
# First, authenticate
curl -s -c cookies.txt -X POST http://192.168.0.7/auth -H 'Content-Type: application/json' -d '{"login":"admin","pass":"admin"}'
# Permanently disable Wi-Fi
curl -s -b cookies.txt -X POST http://192.168.0.7/settings -H 'Content-Type: application/json' -d '{"wifi_perm_disable": true}'
# Reboot to apply the changes
curl -s -b cookies.txt -X POST http://192.168.0.7/cmd -H 'Content-Type: application/json' -d '{"cmd": "reboot"}'
After the reboot GET /settings does not return the wifi group and contains "wifi_perm_disable": true. Sending {"wifi_perm_disable": false} is silently ignored.
This operation is irreversible through the API. To restore Wi-Fi, perform a factory reset with the Config button (hold for 5 seconds) or reflash the device.
Configuration in the Wiren Board controller
The controller and the module are connected to the same network via a router and obtain IP addresses via DHCP
Connection diagram
WB-MGE v.3 module settings, the obtained IP address 192.168.0.196
Port settings in wb-mqtt-serial
Connection diagram
Configuring the Ethernet 2 port on the controller
WB-MGE v.3 module settings, the obtained IP address 10.42.0.176
Port settings in wb-mqtt-serial
The controller is connected to the module over Ethernet, the controller — IPv4 Static IP address, the module — Static IP address
Connection diagram
Configuring the Ethernet 2 port on the controller
WB-MGE v.3 module settings, Static IP address 192.168.1.7
Port settings in wb-mqtt-serial
To control the Modbus devices connected to the module from a Wiren Board controller, the wb-mqtt-serial driver has to be configured:
- In the settings of the wb-mqtt-serial driver add the TCP ports for receiving data from the RS-485-1 and RS-485-2 ports of the module.
- So that the devices appear on the Devices tab in the web interface of the Wiren Board controller, add them automatically, via scanning for Wiren Board devices on the RS-485 bus, or manually, by selecting a template.
- WBIO modules are added manually, by selecting a template. The address of a module depends on what the WB-MGE v.3 is used with:
- A Wiren Board controller —
<WB-MIO Modbus address>:<sequence number of the WBIO module (starting from 1)>. - A third-party controller or software — the addresses are calculated according to the WB-MIO register table.
- A Wiren Board controller —
Updating firmware and resetting settings
Firmware update
The update can be done from the web interface of the module:
- Download the latest firmware version. If the device sees an update, a download button appears next to the firmware version on the Overview and System pages — click it. Or download the file via the direct link latest.bin.
- Open the web interface of the WB-MGE v.3.
- Go to the System page, the Firmware block.
- Click the Choose file button, select the firmware file — the update will start automatically, wait for the process to finish.
After the firmware update the device will be rebooted.
Updating from a channel
Available since firmware version 1.3.0
Starting with version 1.3.0 the module can download and install firmware on its own, without downloading a file by hand. On the System page, in the Firmware card, pick an Update channel:
- Stable — tested versions, the default channel;
- Testing — versions released ahead of the stable ones that are still being trialled.
The module finds out on its own which version is published in each channel and shows it right in the list: «Stable (last 1.1.0)», or «Testing (installed 1.3.0)» when the channel's version is already installed. The selected channel is stored on the device.
When the channel's version differs from the installed one, an Update to last version on channel button appears. On click the module asks for confirmation naming the version, then downloads the firmware from the cloud, installs it, reboots and checks that the expected version is the one now running — no file has to be downloaded or picked by hand. When the installed version matches the channel's version, the button is not shown.
The button installs the version published in the channel, which is not necessarily a newer one. If you are running a version from the testing channel and switch to stable, where an older version is published, the button will offer to install it — that is, to roll back. This is the regular way to return from a testing version to a stable one.
Updating from a file has not gone anywhere and works as before — the Install from file button is right next to it. It comes in handy for versions that are not in the channels, debug builds for example.
Reboot
To reboot the device while keeping the settings, power it off for 10 seconds.
You can also use the Reboot button in the web interface on the System page.
Factory reset
From the web interface
To reset the settings:
- Go to Configuration → System, the Configuration block.
- Click the Reset button in the «Factory reset» row.
Using the Config button
To reset the settings the module has a Config button accessible through a hole in the front cover of the module. There are two ways — they differ in the depth of the reset and in whether a working main firmware is required.
- Factory reset (on a running device, without a reboot). Hold the Config button for 5 seconds with the power on: the firmware rewrites all settings to their default values and applies them immediately. Only the contents of the known settings are rewritten — the NVS partition itself is not erased. The confirmation is several rapid blinks of the Status indicator. The «Reset» button in the web interface gives the same result.
- Complete storage erase (via Factory mode). Needed when the main firmware does not start, or when everything has to be erased for certain. Apply power with the Config button held down to enter Factory mode, then hold the Config button for 5 seconds — the whole NVS partition is erased completely: all keys are deleted, including foreign and corrupted ones. After that the main firmware starts with clean factory settings. The confirmation is several rapid blinks of the Status indicator.
Factory mode
The mode is available only in a module with the factory firmware and serves to restore operation if the main firmware has not started for some reason.
To enable Factory mode apply power to the device with the Config button held down.
In this mode Ethernet is assigned the static IP address 192.168.0.7, the host name wb-mge-factory.local is set over mDNS, and instead of the web interface the module factory firmware upload form is shown.
Updating the built-in WB-MIO firmware
The firmware of Wiren Board devices can be updated over the Modbus protocol. This makes it possible to fix errors found in the firmware at the installation site, and sometimes to add new functions, if this is technically possible. The settings stored in the device memory are not lost during a firmware update.
Instructions:
- Firmware update (video tutorial)
- Resetting settings
- Configuring connection parameters
- Modbus address: find out, reset or change
- Bootloader update
You can learn about the release of a new firmware version in the Built-in WB-MIO firmware changelog.
Using DIY firmware and debugging information
From the factory the module is flashed with the factory software that implements the gateway functions with the ability to update the firmware through the web interface. Nothing needs to be done to use the device as intended.
The gateway firmware is open source (MIT-WB license), repository: github.com/wirenboard/wb-mge.
Flashing connector and debug console
The module is based on the ESP32 chip, and a USB-C programming connector is installed on the board, so you can use the module hardware in your own firmware.
To access the USB-C connector you have to remove the top cover of the device by prying it off from the side with something thin. Debugging information can also be obtained from the module through this connector. When the module is connected to a computer over USB it is detected as an ACM device, which can be opened in any terminal program. In the debugging information you can find the SSID of the access point, the IP address assigned to the module over DHCP and so on.
Important: when using the debug console, first connect the USB-C cable to the computer and to the WB-MGE v.3, and only then apply power to the gateway. This will help avoid a reboot of the device, read more in ERRWB-MGEv30001.
Using your own firmware
If you are an enthusiast or a device developer, we have prepared instructions for flashing the device and examples of alternative firmware for you.
Known issues
WB-MGE v.3 hardware issues/caveats
Device revisions
Images and diagrams
Corel Draw 2018 (font — Ubuntu): Файл:WB-Library.cdr.zip
Visio:
- Wiren Board devices: Файл:WB-Visio-Lib.zip.
- Panels, circuit breakers, contactors, and more by a third-party developer.
Module dimensional drawing (DXF): Файл:WB-MGEv3.dxf.zip
Module dimensional drawing (PDF): Файл:WB-MGEv3.pdf
Symbol library for AutoCAD Electrical: Файл:Wirenboard-AE-base.zip
WB-MGE v.3 PCB
Overall dimensions
Third-party software components
The device firmware contains software components from the ESP-IDF project, distributed under the Apache License, version 2.0. The full text of the license is available in the ESP-IDF project repository. Shipped together with ESP-IDF are the cJSON parser under the MIT license and the Espressif components mdns and esp_io_expander under the Apache 2.0 license.
The web interface is built on the following libraries, all under the MIT license:
- Vue — the interface framework;
- Vue Router — routing between pages;
- Vue I18n — interface translations;
- vue-multiselect — dropdown lists with search;
- ky — the HTTP client;
- unhead — page titles.
The Roboto font is also used, under the SIL Open Font License 1.1.