Miromico Miro EdgeCard mioty® Management
Overview
mioty is a low-power wide-area network (LPWAN) radio protocol designed for IoT applications. It uses telegram splitting, which divides a message into multiple sub-packets sent with error-correcting codes in a set time and frequency pattern, making the transmission resistant to interference and packet collisions. Its main use case is large-scale, high-density deployments, such as those in smart cities.
RAKwireless aims to simplify IoT by making connectivity solutions, including mioty, easily accessible, and is a member of the mioty Alliance.
The WisGate Connect for mioty is RAKwireless' first mioty-enabled product, built on the Miromico Miro EdgeCard for mioty and the WisGate Connect platform. Designed for system integrators, it is an ideal platform to get started with mioty and to deploy multi-protocol solutions on a single device.
Figure 1: WisGate Connect for miotySolution Features
The WisGate Connect for mioty is a CM4-based device with three Mini PCIe slots and one M.2 slot to support multiple radio protocols. All available slots have USB 2.0/3.0 connectivity, SPI bus (Mini PCIe slots #1 and #2), and PCIe (Mini PCIe slot #3 and M.2 slot). This enables many different IoT connectivity solutions, including both LoRaWAN and mioty coverage with a 4G or 5G backhaul.
With three external USB 2.0/3.0 ports, HDMI output, a 2.5 Gb Ethernet port, and a 1 Gb Ethernet port supporting PoE, the WisGate Connect connects to multiple peripherals. It also features two slots for WisBlock modules, allowing connection to industrial devices via RS485, Modbus, CAN bus, and both analog and digital ports.
Focusing on the mioty compatibility, the WisGate Connect for mioty includes a Miromico Miro EdgeCard for mioty. It is a mini PCIe form factor System-on-Module running a full Linux distribution with embedded and licensed mioty base station software.
The card is a computer of its own, on the far side of a point-to-point USB network link. Getting it talking to a mioty backend means configuring the host as well as the card: the connection, the firewall rules that route the card's traffic out, and the base station settings themselves. The mioty-cli tool handles all three.
Card Families
Two firmware families are in the field, and they are managed in completely different ways:
| Family | Managed over | Notes |
|---|---|---|
| Pre-BSM 5.1 | SSH and SCP | The original firmware. The base station and the on-module service center are services you start and stop. |
| BSM 5.1 (BSSCI v1.1.0) | HTTP Config API | The current firmware. The card runs one thing at a time: base station, service center, or IQ capture, and you switch between them. |
mioty-cli detects which family is attached and picks the right backend automatically, so most commands are the same either way. Where a command applies to only one family, the built-in help tags it [<1.1.0] or [>=1.1.0].
Add --verbose (or -v) as the first argument to any command to see which backend was chosen and why:
rak@rakpios:~$ mioty-cli --verbose status
Install and Update the mioty-cli
RAKPiOS 0.9.1 and later ship with mioty-cli. To check what you have:
rak@rakpios:~$ mioty-cli version
mioty CLI utility v0.4.0
To update to the latest release:
rak@rakpios:~$ mioty-cli update
Installing It Elsewhere
The tool is public, and you can read the code or submit issues and fixes at github.com/RAKWireless/mioty-cli.
Download it to a file and run the installer from there:
curl -fsSL -o /tmp/mioty-cli https://raw.githubusercontent.com/RAKWireless/mioty-cli/master/mioty-cli \
&& bash /tmp/mioty-cli install \
&& rm -f /tmp/mioty-cli
curl ... | bash -s -- install looks equivalent, and it is not. The script guards its command dispatcher so that a test harness can source it safely; piping it into bash defeats that guard, so the script defines its functions, installs nothing, and exits successfully. There is no error to notice. Download it to a file first, as above.
The installer puts the tool in ~/.local/bin. RAKPiOS also links it into /usr/local/bin so that non-interactive remote calls, such as ssh gateway 'mioty-cli status', can find it. A non-login shell does not include ~/.local/bin on its PATH.
Dependencies
nmcli, ssh, scp, iptables, curl, jq, mosquitto_sub, mosquitto_pub, and ts (from moreutils) are required. python3 3.7 or later is needed only for firmware-update from a local file. RAKPiOS installs all of them.
Command Reference
Run mioty-cli with no arguments for the full list:
rak@rakpios:~$ mioty-cli
Mioty™ CLI
Utility to configure and manage Miromico's Miro EdgeCard for Mioty™ board.
Firmware tags: [<1.1.0] pre-BSM 5.1 cards only, [>=1.1.0] BSM 5.1 cards only.
Untagged commands work on both. The card family is detected automatically.
Host configuration:
mioty-cli setup --> setups connection and firewall rules
mioty-cli remove --> deletes connection
mioty-cli up --> brings up connection to edge card
mioty-cli down --> brings down connection to edge card
mioty-cli mode --> [>=1.1.0] show what the card is running
mioty-cli mode bs|sc --> [>=1.1.0] switch between base station and service center
mioty-cli status --> [>=1.1.0] show device status (firmware, device_id, uptime, public key)
Base Station configuration:
mioty-cli start --> [<1.1.0] starts the base station, now and on every boot
mioty-cli stop --> [<1.1.0] stops the base station, now and on every boot
mioty-cli restart --> restarts the base station
mioty-cli get <param> --> gets a param from builtin base station
mioty-cli getall --> dumps every base station param
mioty-cli set <param> <value> --> sets a param of the builtin base station
mioty-cli cert <file> --> pushes a certificate file to card
mioty-cli credentials --> shows default credentials based on uniqueBaseStationId
mioty-cli dashboard on|off --> create tunnel to access EdgCard dashboard
mioty-cli reset --> resets base station params to factory values
Service Center configuration:
mioty-cli use_local_sc --> [<1.1.0] points the base station at the on-module service center and starts it
mioty-cli sc-start --> [<1.1.0] starts the service center, now and on every boot
mioty-cli sc-stop --> [<1.1.0] stops the service center, now and on every boot
mioty-cli sc-restart --> [<1.1.0] restarts the service center
mioty-cli sc-getall --> [>=1.1.0] dump the service center configuration
mioty-cli sc-get <param> --> [>=1.1.0] read one service center parameter
mioty-cli sc-set <param> <value> --> [>=1.1.0] write one service center parameter
mioty-cli sc-dashboard on|off --> access the service center dashboard at <host-ip>:8889
mioty-cli messages --> shows messages from service center
mioty-cli register <eui> <shaddr> <nwkkey> --> [<1.1.0] registers an end device
mioty-cli deregister <eui> --> [<1.1.0] unregisters an end device
Tool management:
mioty-cli ssh --> [<1.1.0] ssh to the EdgeCard
mioty-cli firmware-update <url|file> [<sec>] --> [>=1.1.0] install firmware from a URL (the server must support byte-range requests) or a local file; polls until done (budget default 1800s)
mioty-cli reboot [<sec>] --> [>=1.1.0] reboot the card (optional delay)
mioty-cli errors [<n>] --> [>=1.1.0] show last N journal lines (default 50)
mioty-cli license [<file> [force]] --> [>=1.1.0] show licensed features, or install a license file ('force' to install over an existing one)
mioty-cli time --> push the host's UTC clock to the card
mioty-cli version --> show the currest script version
mioty-cli install --> installs tool to user path
mioty-cli update --> updates tool to the latest version
Set Up the Host
setup creates the connection to the card and the firewall rules that let its traffic reach the internet. Run it once:
rak@rakpios:~$ mioty-cli setup
The connection ID is generated fresh, so your output will differ. Root privileges are needed, so it may ask for your password.
Setting up connection and firewall rules
[sudo] password for rak: *****
Connection 'mioty' (a205f647-9df9-486c-9444-b340d567df7b) successfully added.
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/8)
The tool uses NetworkManager, the default network manager on RAKPiOS, so the new connection shows up alongside the others:
rak@rakpios:~$ nmcli c
NAME UUID TYPE DEVICE
Wired connection 1 631c4c05-fef2-3ed1-b2c7-72c52ab32bca ethernet eth0
lo 5d01c541-459b-47bb-b18d-90154fadbc42 loopback lo
mioty a205f647-9df9-486c-9444-b340d567df7b ethernet eth2
Wired connection 3 def4ec7f-f26c-3827-81e0-e5b972619c14 ethernet eth3
docker0 21d17c70-5b59-4640-aa0d-d062d9b92c7d bridge docker0
Wired connection 2 e9f8466f-2c2a-3135-b522-4764946f5ad0 ethernet --
up and down bring that connection up and down afterwards; remove deletes it.
Neither card family has a real-time clock, and both boot at a fixed date in the past. up pushes the host's UTC clock to the card every time the link comes up, and restarts the base station if the correction was large enough to have been blocking it.
Because the card has no clock to keep, this has to happen after every card reboot, which is what up handles. mioty-cli time pushes it again at any point. Refer to Certificate Verification Failed for what goes wrong when the clock is not set.
Provision the Base Station
Your base station may already be pre-provisioned by Miromico on Loriot, a platform provider offering both LoRaWAN and mioty backends. Check the Preprovisioned Base Stations annex first. If your base station is pre-provisioned, you cannot create a new base station with the same unique ID and should log in with the generated credentials instead.
To provision it yourself:
1. Create a Loriot Account
Create an account on the Loriot EU3 cluster, the one with mioty support, and log in.
Figure 1: Loriot login page2. Create a Network
Under Networks, click New mioty Network in the left menu. Enter a name and an optional location.
3. Retrieve the Unique Base Station ID
On the gateway:
rak@rakpios:~$ mioty-cli getall
Base station parameters
uniqueBaseStationId : 9C-65-F9-FF-FE-55-44-33
baseStationName : miro Edge mioty
baseStationVendor : Miromico
baseStationModel : EDGE-GW-MY-868
serviceCenterAddr : eu3.loriot.io
serviceCenterPort : 727
tlsAuthRequired : true
profile : eu1
Note the uniqueBaseStationId, check that serviceCenterAddr is eu3.loriot.io, and that serviceCenterPort is 727.
On BSM 5.1 firmware, getall reports whether each certificate and key is present rather than showing its value. The card does not hand a private key back, by design. Refer to Certificates.
If the card is currently running the service center, getall will tell you to switch modes rather than show base station settings. The settings are intact and come back when you switch. Refer to Modes.
4. Create a Base Station On Loriot
- On the network page in the Loriot dashboard, click Add Base Station.
Figure 1: Add base station to Loriot- Enter the unique ID you retrieved into the Base Station EUI field, without the separators. Optionally add a location, and click create.
5. Retrieve Credentials From Loriot
- Open the Certificate option in the left menu of the base station page.
- You need three files:
root_ca.cer: The Loriot root certificate, common to all base stationsbstation.cer: This base station's certificatebstation.key: This base station's certificate key
- Download the TLS CA Certificate shown on the Certificate page and save it as
root_ca.cer. - Click Generate TLS Certificate and download both files, as
bstation.cerandbstation.key.
6. Save the Credentials On the EdgeCard
Copy the three files to the gateway, with scp for instance, then push each one to the card:
rak@rakpios:~$ mioty-cli cert root_ca.cer
rak@rakpios:~$ mioty-cli cert bstation.cer
rak@rakpios:~$ mioty-cli cert bstation.key
Certificates
The card needs all three files before it will connect to a service center, and set and cert warn while only part of the set is present.
The card will not give it back. On current firmware getall reports only whether each of the three is present, never its contents. If you lose bstation.key, you have to generate a new certificate pair on Loriot and push both again.
Start and Stop the Base Station
rak@rakpios:~$ mioty-cli start
Starting base station
Running and running-at-boot are one setting. start starts the base station and sets it to start on every boot; stop stops it and stops it coming back; restart follows the same rule. The card always comes back in whatever state you last put it in.
This matters more than it sounds. Previously, the two were separate, and a card that had been started but never enabled would work perfectly until something power-cycled it. It would then come back dead, possibly months later, with nothing tying the outage to the command that caused it.
enable and disable still work, and are now simply other names for start and stop.
On BSM 5.1 firmware the base station is always running, and the service center is a mode rather than a service, so these verbs do not apply. Use mode instead.
Modes (BSM 5.1)
A BSM 5.1 card runs exactly one of: a base station, a service center, or IQ capture.
rak@rakpios:~$ mioty-cli mode # what is the card running, and may it run a service center?
rak@rakpios:~$ mioty-cli mode sc # switch to the built-in service center
rak@rakpios:~$ mioty-cli mode bs # switch back to the base station
Switching loses nothing: the settings and certificates of the mode you leave are kept and come back when you return. But the card only reports configuration for whatever it is currently running, so get, getall, and credentials against a card running the service center will tell you to switch rather than show you stale values.
Write commands check what the card is running before sending anything and refuse if it does not match, so a base station write cannot stop a running service center by accident. Switching to the service center requires a license that allows it; without one, nothing is sent to the card at all.
The Service Center
Once the card is running the service center:
rak@rakpios:~$ mioty-cli sc-getall # dump its configuration
rak@rakpios:~$ mioty-cli sc-get <param> # read one parameter
rak@rakpios:~$ mioty-cli sc-set <param> <value> # write one parameter
rak@rakpios:~$ mioty-cli messages # watch traffic
A write restarts the service center, and for a few seconds afterwards, it still reports its previous settings. This is expected and does not indicate a failed write. Run sc-getall again a moment later.
Some values shown by sc-getall are managed by the card itself. sc-set refuses changes to these values rather than pretending to write them.
register and deregister are not currently supported on either card family. The message format for them is undocumented, so they fail with an error rather than appearing to work.
On Pre-BSM 5.1 Cards
There the service center is a service, started and stopped like the base station:
rak@rakpios:~$ mioty-cli sc-start | sc-stop | sc-restart
use_local_sc points the base station at the service center built into the card, starts it, and confirms the two actually paired.
use_local_sc TURNS TLS OFFIt has to: the built-in service center listens in the clear and has no certificate, so a base station demanding mutual TLS cannot pair with it. That is safe here because both ends are inside the same box, but it leaves tlsAuthRequired set to false.
Before pointing the card back at a remote service center, put it back:
rak@rakpios:~$ mioty-cli set serviceCenterAddr <your-service-center>
rak@rakpios:~$ mioty-cli set serviceCenterPort 727
rak@rakpios:~$ mioty-cli set tlsAuthRequired true
rak@rakpios:~$ mioty-cli restart
Monitoring
Local Dashboard
The card has an embedded dashboard. Expose it on the host with:
rak@rakpios:~$ mioty-cli dashboard on
It becomes reachable at http://<host-ip>:8888/, from any machine that can reach the gateway. Close it with mioty-cli dashboard off.
Figure 1: Base station local dashboardThe service center has a dashboard of its own, at <host-ip>:8889:
rak@rakpios:~$ mioty-cli sc-dashboard on
The two are independent. Opening or closing one leaves the other alone.
dashboard on CAN OUTLIVE A REBOOTOn current firmware the setting survives a restart, so a forgotten dashboard on leaves the card's debug interface reachable until you actually run dashboard off. The command warns you when that applies.
Card Status
On BSM 5.1 firmware, status is the single most useful diagnostic:
rak@rakpios:~$ mioty-cli status
It reports the firmware version, device ID, and uptime; what the card is running; whether its session with the service center is up, and the card's own reason when it is not; the configuration write model in use; and what the card is licensed for.
errors [<n>] shows the last N lines of the card's journal, 50 by default.
Loriot Monitoring
- Back in Loriot, go to Networks and, under mioty Networks, click the name of your network.
- Click the entry matching your base station's EUI. You get a page with live data and a PING button once the connection is established.
Figure 1: Loriot gateway dashboardProvisioned sensors appear under Applications: click the application name under mioty Applications and you will find them listed under End Points.
Figure 1: Loriot end-point dashboardFirmware Updates and Licenses
Firmware
rak@rakpios:~$ mioty-cli firmware-update <url|file> [<seconds>]
The command polls until the update finishes, fails, or the budget runs out. The default is 1800 seconds. A failed update stays failed until the card is rebooted.
- From a URL, the card downloads in chunks, so the server must support HTTP byte-range requests.
- From a local file, the bundle is served to the card over the point-to-point link only, never the LAN. This needs
python33.7 or later on the host.
On success, the new firmware is in the card's standby slot. Run mioty-cli reboot to activate it.
Licenses
rak@rakpios:~$ mioty-cli license
This prints what the card is licensed for, feature by feature. Read the per-feature lines rather than the overall valid flag on the first one. That is every feature ANDed together, so a single expired grant makes the whole license look bad.
license <file> installs a license, but refuses if the card already holds one: installing over it may not be reversible and could drop a grant you still need. Use license <file> force if you have decided to go ahead.
Setting Parameters
rak@rakpios:~$ mioty-cli set <param> <value>
Values are validated before being sent. For most parameters that means letters, digits, spaces, and . _ : / -. Anything else is rejected with a message naming what is allowed. Every write is confirmed and read back, so a write that did not take reports an error instead of success.
set uniqueBaseStationId accepts a bare, hyphenated, or colon-separated EUI-64 in any case, and normalizes it to the form the card requires. Do not hand-format it, and do not assume a value the card accepted was one it understood.
Resetting a Card
rak@rakpios:~$ mioty-cli reset
reset discards configuration changes that have not been written to flash. On current firmware, it is not established whether it also clears the flashed configuration. The vendor documents it as the way back to factory defaults, which would mean losing the card's identity and certificates. Because of this potential loss, the command warns you and asks you to type yes before doing anything. It also refuses outright if it is not attached to a real terminal.
Troubleshooting
Certificate Verification Failed
ERR bsi cannot connect to service center <host>:727
(X509 - Certificate verification failed, e.g. CRL, CA or signature check failed)
Check the clock before you touch the certificates. Neither card family has a real-time clock. Both boot at a fixed date in the past, around 14 months for BSM 5.1 and as much as four years for pre-BSM 5.1 cards. If the clock is still in the past, the service center's certificate is not yet valid. The card's own certificate may also be considered invalid if it was issued recently.
The message names certificates, so the natural response is to go and re-issue perfectly good ones.
- On BSM 5.1,
mioty-cli statusshows the card's time. A card with working internet corrects itself over NTP within a minute or two of booting, so you may only see this in a short window after a reboot. - On pre-BSM 5.1,
mioty-cli sshin and rundate. These cards never correct themselves: the vendor's start script switches the NTP client off and points it at the gateway rather than the internet.
The fix either way is mioty-cli up or mioty-cli time.
A Value Reverts On Its Own
On pre-BSM 5.1 cards the tool keeps a local record of what it has pushed, under ~/.local/share/mioty-cli/, and get and getall warn you when the card disagrees with it. That warning is worth reading: the card can accept a value and then quietly ignore it, and this is how you find out.
The Card Can Send But Never Receives
Fixed in mioty-cli 0.3.0 and later. If you are on an older version, upgrade. setup now installs a RELATED,ESTABLISHED forwarding rule for the return path.
Without this rule, replies match no rule and hit the default FORWARD policy. This policy is ACCEPT on a stock host but DROP on any host running Docker. On such a host, the card silently loses all internet access, including DNS. As a result, the base station could not resolve its service center, even though the outbound rules still show traffic passing.
Nothing Reaches the Card At All
mioty-cli distinguishes "no card attached" from "card attached, connection down", and probes the card independently of NetworkManager, so it will not tell you to run up when up cannot possibly succeed. If it reports no card, check that the module is seated and that the gateway sees its USB interfaces.
Annexes
Preprovisioned Base Stations
The base station may come pre-provisioned by Miromico on Loriot. If it does, you will not be able to create a new base station with the same unique ID, and should log in with the default credentials generated by Miromico instead.
- Open Loriot EU3 cluster in a browser. You get a login page.
Figure 1: Loriot login page- The Miro EdgeCard comes with a username and password derived from the base station's EUI. Ask the tool for them:
rak@rakpios:~$ mioty-cli credentials
Default credentials (mind these might have changed)
Service center : https://eu3.loriot.io
Username : pockit+5cc7a1@miromico.io
Password : a125cc_B347a1
- If you change the default credentials on the Loriot dashboard, these are no longer valid. Neither
mioty-clinor the EdgeCard is told that they changed. - If you have not changed them but still cannot log in, your base station is probably not preprovisioned. Go back to Provision the Base Station and follow the steps there.
