Mqtt5nano device commands. - awootton/knotfreeiot GitHub Wiki
Device commands
Here is a description of the base commands provided by the mqtt5nano library. Version v0.5.2
Note that the 'unlock' icon, π, means that the command does not require encryption. (That lock is open even if it doesn't look like it.)
help returns this list from your device which might be different depending on the version. Applications (eg thermometer, scroller, etc) will have additional commands. It is easy to add your own commands (see this wiki).
The commands accessible 6 by 6 methods:
- In a Serial Monitor/Terminal (which never requires encryption) when connected by usb.
- On the local wifi network by HTTP eg. http://yourthing.local./help
- By HTTP at knotfree.net eg. https://yourthinglongname.knotfree.net/help
- Via MQTT where the Topic Name is the long name of the device. For example "yourthinglongname", or "a-thermometer-demo_iot".
- Via just the name of the thing. eg. http://a-thermometer-demo.iot/help if you own the name "a-thermometer-demo.iot", via knotfree.net for a penny AND you are using the knotfree dns server (149.28.250.163) or if ICANN suddenly approves my application.
- Via just the name of the thing. eg. (http://a-thermometer-demo.xyz/help)[http://[a-thermometer-demo.xyz/help] if you own the name "a-thermometer-demo.xyz",from squarespace.com for $20.
The HTTP versions of the commands work in any browser but the encrypted commands are impossible to type by hand. In the browser a '/' is used between the words in a command instead of a space. as in http://a-thermometer-demo.xyz/get/c
[favicon.ico] shortest png in the worldπ
The web browsers of the world constantly ask for this. It returns a PNG file of a green square. This is the only command that doesn't return text output.
[freemem] count of free memory
This command returns the free memory available on the device. A typical value for an ESP8266 is 25296
[get WiFi] WiFi name
This will return the name of your wifi, if set by set wifi. Aka SSID.
[get admin hint] admin key start.π
The device will only accept commands encrypted by a particular 'admin' key from the dashboard app (knotfree.net)
This hint is the first 8 characters of the admin public key. eg. 3v9teOO_
[get local peers] list http servers on local net.
Every 'thing' you have running on your wifi has a short name and these short names are also addresses. This command will list them all. At my house this list looks like:
0) SEC30CDA7BEC556.local
1) tempa.local
2) test5.local
3) tempb.local
4) tempw.local
5) scroller.local
6) LS710DA81.local
Items 1 to 4 are thermometers. The scroller is a scrolling display (see my substack The other two are printers that have web pages showing their status. (bet you always wondered how that works π)
[get long name] long name is unique over the world.π
This is the long name that you set with set long name during initialization of the device. This is also part of the URL at knotfree.net. Eg. If the long name is 'get-unix-time' then the URL http://get-unix-time.knotfree.net/ will access that device.
[get pass] WiFi password
This doesn't actually return your wifi password. That is a secret. It return '********' if the password is set.
[get pubk] device public key.π
When you set the password for the device a private key and a public key are created. The private key is a secret but the public key is needed to encrypt commands. This returns that public key. Example: iP8H8BJAvNsac3rI2SFXvGiHmDqZV3vxFFLEWE-8bnE
[get short name] name on local net.π
This returns the short name you set with set short name. Eg, demotemp
[get time] seconds since 1970π
This is the literally the number seconds since midnight new years eve of December 1969 in Greenwich England. It's a standard way to keep time. You can convert it to a real time at this website: https://www.epochconverter.com/
[get token] returns 'claims' from token.
We never show the token once it's set but a token has 'claims' which show what it's permissions are. The important ones are the expiration date and the number of connections allowed. Here's an example:
{"exp":1682731103,"iss":"_9sh","jti":"r7vpi15lz2l2oa6jjafj9asd","in":152,"out":152,"su":100,"co":4,"url":"knotfree.net"}
Which means 4 is the max connections("co") and feeding the exp to the epoc convertor above yields: April 28, 2023 as the expiration date. (The dashboard at knotfree does this for you.)
[get wifi list] list of local wifi nets
If you have set up your wifi before you know that your neighbors also have wifi and you have to pick the one that is yours. The command get wifi list returns a list of wifi's available. eg.
1: Connected (-/)
2: dcc-bdrmlge (-/)
3: woot2 (-/)
4: ATTEIgF84I (-/)
5: DIRECT-USSCX-3400 Series (-/)
6: DIRECT-K9C43x Series (-/)
7: woot2 (-/)
8: ORBI29-IoT (-/)
9: woot2 (-/
woot2 is mine.
[help] lists all commands.π
lists all the commands.
[served] count of requests served since reboot.
Returns the number of commands processed.
[set admin password] +1 the passphrase for admin access.
This will set the admin public key that your phone will be using to encrypt commands. It also computes the private key but then forgets it. (The +1 means that the command needs an additional word. Normally used at setup. If used in the console you may have to restart the device by unplugging it)
[set device password] +1 the passphrase for this device.
This will set the public key and the private key for the device. The private key is hidden but the pubic key can be retrieved with get pubk
(The +1 means that the command needs an additional word. Normally used at setup. If used in the console you may have to restart the device by unplugging it)
[set long name] +1 set long name is unique over the world
This will set the 'long name' that will also be the start of the URL for accessing your device over the web. It can only be lowercase, numbers and '-'. It can't match anyone else so make it long, personal, and uique. It's going to be like a DNS name except free and only machines will use it. (The +1 means that the command needs an additional word. Normally used at setup. If used in the console you may have to restart the device by unplugging it)
[set pass] +1 set WiFi pass
Provide the password to your wifi.
[set short name] +1 the '.local.' name.
This will be the short name that will be like the DNS, or domain name, for your thing on your local wifi network. It isn't used now but it enables 'local only mode' which is where your IOT devices don't use the cloud or the knotfree server. Google Chrome threw a wrench in that but it's coming soon. This name can only be lowercase, numbers, and '-' (The +1 means that the command needs an additional word. Normally used at setup. If used in the console you may have to restart the device by unplugging it)
[set time] +1 adjust the clock as necessary. Not safe.
There's no need to do this. If you get it wrong then all the encryption becomes broken until the device is restarted.
[set token] +1 set access token
This is the access token which your device needs for access to the knotfree.net server. Get one at knotfree.net. Get better ones by following me on Twitter or even better ones by following me on Substack Replacing soon to be expired tokens can be done from the from the app at knotfree.net
[set wifi] +1 set WiFi name
Set the name of your wifi.
[settings erase] +1 erase all the settings with code KILLMENOW
For when you want to start all over again from scratch. If you do this then you will have to go through the whole startup sequence again. Do this before you give it to someone else
[status] mqtt status
This return diagnostic information about the mqtt connection. eg.
admin hint:3v9teOO_ admin public key:3v9teOO_okv-6jiQzNVcOPXLGfAxT2E70pQwC-7eoHo public key:iP8H8BJAvNsac3rI2SFXvGiHmDqZV3vxFFLEWE-8bnE long name:demo-small-window-allow-should-engine token:{"exp":1682731103,"iss":"_9sh","jti":"r7vpi15lz2l2oa6jjafj9asd","in":152,"out":152,"su":100,"co":4,"url":"knotfree.net"}
Note that since there are two commands with the name 'status' they both run.
[status] WiFi status
This returns diagnostic information about the wifi connection. eg;
wifi-connected:true MDNS:true ssid:woot2 pass:******* short-name:demotemp ip-addr:192.168.86.37
Note that since there are two commands with the name 'status' they both run. `
[uptime] time since last reboot.
Returns an elapses time in the format hours minutes:seconds. eg. 1 hours 45:44
[version] mqtt5nano version
Returns the version of mqtt5nano on the device. eg v0.5.0 mqtt5nano