This is a CLI script to setup and manage Miromico's Miro EgdeCard for Mioty.
The CLI detects which firmware family is attached automatically. Run any verb with --verbose (or -v) as the first argument to see which backend was selected.
- Pre-BSM 5.1 — original firmware family, managed over SSH/SCP. All
Edge card configurationandService center configurationverbs apply. - BSM 5.1 (BSSCI v1.1.0) — current firmware family, managed over an HTTP Config API.
Required: nmcli, ssh, scp, iptables, curl, jq, mosquitto_sub, mosquitto_pub, ts (moreutils).
python3 (3.7+) is needed only for firmware-update against a local file.
Users can use remote bash execution script to install/upgrade mioty-cli.
To install:
curl https://raw.githubusercontent.com/RAKWireless/mioty-cli/master/mioty-cli -sSf | bash -s -- install
After the installation/upgrade is finished, users can use the command mioty-cli to get a list of available options.
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
A BSM 5.1 card runs exactly one of: a base station, a service centre, or IQ capture.
mioty-cli mode # what is this card running, and may it run a service centre?
mioty-cli mode sc # switch to the built-in service centre
mioty-cli mode bs # switch back to the base stationSwitching modes loses nothing: the settings and certificates of the mode you leave are kept, and come back when you switch back. But the card only reports configuration for whatever it is currently running, so get, getall and credentials against a card running the service centre will tell you to switch rather than show you anything.
Write verbs check what the card is running first and refuse if it doesn't match, so a base-station write can't stop a running service centre by accident. Switching to the service centre needs a licence that allows it; without one, nothing is sent to the card at all.
Once the card is running the service centre:
mioty-cli sc-getall # dump the service centre configuration
mioty-cli sc-get <param> # read one parameter
mioty-cli sc-set <param> <value> # write one parameter
mioty-cli sc-dashboard on|off # reach its dashboard at <host-ip>:8889
mioty-cli messages # watch trafficThe base station's own dashboard (dashboard, at <host-ip>:8888) keeps working while the card runs the service centre, so the two are independent — opening or closing one leaves the other alone.
sc-dashboard works on pre-BSM 5.1 cards too, where it reaches the service centre's dashboard while that service is running. It will tell you if it isn't.
A few of the values sc-getall shows are managed by the card itself; sc-set refuses those rather than pretending to write them.
A write restarts the service centre, and for a few seconds afterwards it still reports its previous settings. That is expected, not a failed write — run sc-getall again a moment later.
register and deregister are unsupported on both card families: the message format for them isn't documented, so they fail loudly rather than appearing to work.
Running and running-at-boot are one setting. start starts a service and sets it to start on every boot; stop stops it and stops it coming back. restart does the same as start for a service that was stopped. So the card always comes back in whatever state you last put it in:
mioty-cli start | stop | restart # the base station
mioty-cli sc-start | sc-stop | sc-restart # the on-module service centre (-NM cards)enable and disable are now just other names for start and stop. They still work.
On BSM 5.1 the base station is always running and the service centre is a mode rather than a service, so these verbs don't apply there — use mode instead.
use_local_sc switches an -NM card from a remote service centre to the one built into the card, and reports whether the two actually paired. On BSM 5.1 the equivalent is mode sc.
It turns TLS off, and it has to: the built-in service centre listens in the clear and has no certificate, so a base station demanding mTLS cannot pair with it. That is safe here — both ends are inside the same box — but it means tlsAuthRequired is left false. Before pointing the card back at a remote service centre, put it back:
mioty-cli set serviceCenterAddr <your-service-centre>
mioty-cli set serviceCenterPort 727
mioty-cli set tlsAuthRequired true
mioty-cli restartThe CLI adapts how it writes configuration to your card's firmware, and picks the safe behaviour whenever it can't tell. mioty-cli status reports which it used and --verbose says why; MIOTY_CLI_CONFIG_MERGE=1 or =0 overrides it if you ever need to.
On older firmware it also keeps a local record of what it has pushed (under ~/.local/share/mioty-cli/), and get/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.
set uniqueBaseStationId accepts a bare, hyphenated or colon-separated EUI-64 in any case and normalises it to the form the card requires — so don't hand-format it, and don't assume a value the card accepted was one it understood.
Push each of root_ca.cer, bstation.cer and bstation.key with cert <file>. The card needs all three before it will connect to a service centre, and set/cert warn while only part of the set is present.
Keep your own copy of the private key. The card will not give it back — on current firmware getall reports only whether each of the three is present, never its contents.
Neither card family has a real-time clock, and 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.
A BSM 5.1 card with working internet corrects itself over NTP within a minute or two of booting, so there you may only see the symptom below in a short window after a reboot. A pre-BSM 5.1 card never does: its NTP client is switched off by the vendor's own start script and points at the gateway rather than the internet, so it stays wrong until the host sets it.
That matters far more than it sounds, because of how it fails. With the clock in the past, the service centre's certificate has not started being valid yet, and neither has the card's own certificate if you uploaded it recently. The base station reports:
ERR bsi cannot connect to service center <host>:727
(X509 - Certificate verification failed, e.g. CRL, CA or signature check failed)
That message names certificates, so the natural response is to go and re-issue perfectly good ones. If you see it, check the clock first — mioty-cli status on BSM 5.1, or ssh in and run date on a pre-BSM 5.1 card.
up pushes the host's clock to the card every time the link comes up, on both families, and restarts the base station when the correction was big enough to have blocked it. Run mioty-cli time to push it again at any point. Because the card has no clock to keep, this has to happen after every card reboot — which is what up is for.
firmware-update <url|file> [<seconds>] takes either a URL or a local file, and polls until the update finishes, fails, or the budget runs out (default 1800s). A failed update stays failed until the card is rebooted.
The card downloads in chunks, so a URL must be hosted on a server that supports byte-range requests. A local file is served to the card over the direct link only — never the LAN — and needs python3 (3.7+) on the host.
On success the new firmware is in the card's standby slot: reboot to activate it.
license shows what the card is licensed for, feature by feature. Read the per-feature lines rather than the overall valid on the first one — that is every feature ANDed together, so a single expired grant makes the whole licence look bad.
license <file> installs a licence, but refuses if the card already holds one: it may not be reversible, and it could drop a grant you still need. Use license <file> force if you have decided to do it anyway.
Parameter values are checked before being sent: for most parameters that means letters, digits, spaces and . _ : / -. Anything else is rejected, with a message naming what is allowed. Writes are confirmed and read back, so a write that didn't take reports an error rather than success.
status reports what the card is running, whether its session with the service centre is up (and the card's own reason when it isn't), and what it is licensed for, alongside the card's firmware version, uptime and device id.
dashboard on|off works on both card families and puts the card's dashboard at http://<host-ip>:8888/.
On current firmware this survives a reboot, 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.
reset discards configuration changes that have not been written to flash. On current firmware, whether it also clears the flashed configuration is not established — the vendor documents it as the way back to factory defaults, which would mean losing the card's identity and certificates. So there it warns, and asks you to type yes before doing anything. Run it from a real terminal; it refuses outright rather than hang waiting for input that will never arrive.