Skip to content
English
Do you need help? Customer portal
neowit.io
  • There are no suggestions because the search field is empty.

Gude - Provisioning several units at once

Point a whole rack at Neowit with one command, credentials and all. For whoever sets up a rack, or inherits units that were configured inconsistently.

A Gude unit's configuration file is a list of its own console commands, and a unit accepts one over its HTTP interface. So provisioning is: generate the MQTT lines each unit needs, upload, restart. That covers everything — broker, TLS, username, password and client ID included — so a unit fresh out of the carton takes the same one command as one that is already running.

Before you start

  • Python 3.7 or newer. Nothing to install: the script uses the standard library only.
  • The units reachable on your network. Their web login too, if they have one — many racks run with the unit's HTTP password off, and then nothing is needed.
  • The connection details from the integration — see Gude setup.

Get the script

gude_provision.py — one file. Put your credentials in the environment so they stay out of your hell history:

export GUDE_MQTT_USERNAME='<the integration id>'
export GUDE_MQTT_PASSWORD='key:<id>:<secret>'
export GUDE_HTTP_PASSWORD='<the units web password, if they have one>'

See what it would do

List each unit as its address and the client ID you want it to have. Nothing is changed without --apply:

python3 gude_provision.py --dry-run --unit 10.0.0.11=pdu1 --unit 10.0.0.12=pdu2
10.0.0.11
  unit           Expert Power Control 1121-1 (firmware 1.2.3)
  client id      pdu1
    mqtt 1 server set "mqtt.neowit.io"
    mqtt 1 port set 8883
    mqtt 1 tls enabled set 1
    ...
  to change      2 setting(s)
    qos: asked for 1, unit reports 0
    client_id: asked for 'pdu1', unit reports 'epc-01'

Those lines are the file that would be uploaded, and the differences underneath come from asking each unit what it currently has.

Apply it

python3 gude_provision.py --apply --unit 10.0.0.11=pdu1 --unit 10.0.0.12=pdu2
10.0.0.11
  unit           Expert Power Control 1121-1 (firmware 1.2.3)
  client id      pdu1
  config         uploaded
  restart        requested
  status         back up, settings confirmed

2 provisioned, 0 failed

Each unit restarts once and comes back configured. Outlets keep their state across the restart. Settings confirmed means the script re-read them from the unit afterwards, so an upload that didn't take is reported as a failure rather than a success.

Note: client IDs must be unique per unit — two units sharing one disconnect each other. The script refuses a run that repeats one. Maximum 23 characters.

What it sets

Setting Value
Broker, port, TLS mqtt.neowit.io, 8883, on
Username, password From the integration — the same on every unit
Client ID Yours, per unit
Topic prefix de/gudesystems/epc/[mac], the factory default
QoS, clean session 1 and on, so commands aren't dropped or queued up and replayed late
Keep-alive 60 seconds
Reading interval 300 seconds. Outlet changes arrive immediately whatever this is — it only paces the power figures
Permit CLI commands On. Without it a unit reports readings but ignores every switch and power-cycle command

The file applies on top of each unit's current configuration, so nothing outside the MQTT section — network settings included — is touched.

Re-provisioning units that already work

Add --keep-credentials and the username and password are left alone. Useful for pushing a settings change across a rack that is already connected, and the run then needs no MQTT secrets at all.

Without the script

Configure one unit through its web interface, then on its maintenance page use Config File Export, keep the mqtt lines, change the client ID for the next unit, and upload the file there under Config Import File Upload followed by Restart Device.

Note: an exported configuration carries the MQTT username and the password hash. Export over HTTPS and treat the file as a credential.

Related