MQTT Support
How to integrate HAM Systems sensors and devices using MQTT with external services
Lefteris Chatzipetrou
Last Update 3 bulan yang lalu
Starting from firmware version 1.1.20, all HAM Systems devices can publish readings and accept commands using MQTT. The MQTT connection is parallel to the existing secure encrypted connection to HAM Cloud, meaning you can use both at the same time. There can only be one MQTT connection active at a time.
If you only want to have the MQTT connection and remove the connectivity to HAM Cloud, you can get in touch and we can set it up for you
For state and hardware definitions refer to this article
Why MQTT
MQTT has become an industry standard for IoT devices. It efficient and supported by a lot of cloud and local automation systems like Home Assistant. It is very similar to the philosophy of our own protocol, meaning it is a publish-subscribe model.
One main difference compared to using our real time API directly is that, with our API you can subscribe the all the state of a device, while MQTT uses topics. State access on our API determined completely from the permissions sets from our app. That mean that MQTT needs some extra configuration on your side in order to work.
In both cases you need implement state decoding and in both cases, state is provided in JSON format.
You can read more about MQTT here. The rest of the article assumes your are familiar with the concepts of the protocol.
Topics
State is published to:
ham/SERIALNO/readings
ham/SERIALNO/settings
ham/SERIALNO/stat
e.g.
ham/e11:3721/settings {"id":"HAM ThermoSenseX1","S":{"iTS_TR0":0,"iTS_TC0":0,"iTS_TR1":0,"iTS_TC1":0,"iTS_TR2":0,"iTS_TC2":0,"iTS_TR3":0,"iTS_TC3":0,"iTS_TR4":0,"iTS_TC4":0,"iTS_TR5":0,"iTS_TC5":0,"iDSTADR0":576460820704723496,"iGIALR":492371968,"iBUZM":2,"iS_PO":9002,"W_S":"71","W_P":"PASSWORD","W_EAP_I":"","W_EAP_U":"","W_EAP_P":"","iALC":0,"iDMC":0,"iOM":0,"iRFTM":0,"iPV4":0,"iFFU":0,"iFNOBLEU":0,"sS_AD":"node0.hamsystems.eu","sAPN":"","sAPNU":"e.com","sAPNP":"","iUP":0,"iFRP":0}}
ham/e20:143/stat {"serialno":"e20:143","uptime":483,"version":"1.1.22","build":"31747","romhash":"0779427398978a3775e30d813ee6ee54fada18721222a00c96387c919fe9d6c0","sdk_build":"v5.5-beta1-215-gcf8dad0746-dirt","roms":0,"nroms":2,"if":"wifi","rssi":-55,"chan":12,"schan":0,"ip":"192.168.1.213","ipv6":"1000:0:ffff:ffff:0:0:200:0","mac":"40:4c:ca:55:c6:c0","wifihash":"b12536c2f24a436fe10c4ef910613da766b1975a28a57e10188c75ff66dbf444","sim_imei":"","sim_imsi":"","sim_iccid":"","sim_oper":"","nm":{"rx":1241,"rx_period":31,"tx":1241,"tx_period":12}}
You can set outputs (equivalent to WRITE command) by publishing to the topic ham/SERIALNO/outputs/set
e.g.
0,200 to ham/e20:10/outputs/set
You can send arbitrary commands to ham/SERIALNO/command
To configure MQTT you have to use commands MQTTSET. The syntax is:
MQTTSET "URL","USERNAME","PASSWORD"
e.g.
MQTTSET "mqtt://broker.hivemq.com:1883","",""
If you want to use an encrypted connection (recommended) you also have to configure the CA root certificate of your server. You can get that using openssl:
openssl s_client -connect mqtt.example.com:8883 -showcerts </dev/null 2>/dev/nullThe root certificate is the last with the latest expire date.
To set the CA certificate you use the command MQTTCA with syntax:
MQTTCA URL_ENCODED_PEM_FORMATExample:
MQTTCA -----BEGIN%20CERTIFICATE-----%0AMIIEyDCCA7CgAwIBAgIQDPW9BitWAvR6uFAsI8zwZjANBgkqhkiG9w0BAQsFADBh%0AMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3%0Ad3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBH%0AMjAeFw0yMTAzMzAwMDAwMDBaFw0zMTAzMjkyMzU5NTlaMFkxCzAJBgNVBAYTAlVT%0AMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxMzAxBgNVBAMTKkRpZ2lDZXJ0IEdsb2Jh%0AbCBHMiBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTCCASIwDQYJKoZIhvcNAQEBBQAD%0AggEPADCCAQoCggEBAMz3EGJPprtjb%2B2QUlbFbSd7ehJWivH0%2Bdbn4Y%2B9lavyYEEV%0AcNsSAPonCrVXOFt9slGTcZUOakGUWzUb%2Bnv6u8W%2BJDD%2BVu%2FE832X4xT1FE3LpxDy%0AFuqrIvAxIhFhaZAmunjZlx%2FjfWardUSVc8is%2F%2B9dCopZQ%2BGssjoP80j812s3wWPc%0A3kbW20X%2BfSP9kOhRBx5Ro1%2FtSUZUfyyIxfQTnJcVPAPooTncaQwywa8WV0yUR0J8%0AosicfebUTVSvQpmowQTCd5zWSOTOEeAqgJnwQ3DPP3Zr0UxJqyRewg2C%2FUaoq2yT%0AzGJSQnWS%2BJr6Xl6ysGHlHx%2B5fwmY6D36g39HaaECAwEAAaOCAYIwggF%2BMBIGA1Ud%0AEwEB%2FwQIMAYBAf8CAQAwHQYDVR0OBBYEFHSFgMBmx9833s%2B9KTeqAx2%2B7c0XMB8G%0AA1UdIwQYMBaAFE4iVCAYlebjbuYP%2Bvq5Eu0GF485MA4GA1UdDwEB%2FwQEAwIBhjAd%0ABgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwdgYIKwYBBQUHAQEEajBoMCQG%0ACCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdpY2VydC5jb20wQAYIKwYBBQUHMAKG%0ANGh0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydEdsb2JhbFJvb3RH%0AMi5jcnQwQgYDVR0fBDswOTA3oDWgM4YxaHR0cDovL2NybDMuZGlnaWNlcnQuY29t%0AL0RpZ2lDZXJ0R2xvYmFsUm9vdEcyLmNybDA9BgNVHSAENjA0MAsGCWCGSAGG%2FWwC%0AATAHBgVngQwBATAIBgZngQwBAgEwCAYGZ4EMAQICMAgGBmeBDAECAzANBgkqhkiG%0A9w0BAQsFAAOCAQEAkPFwyyiXaZd8dP3A%2BiZ7U6utzWX9upwGnIrXWkOH7U1MVl%2Bt%0AwcW1BSAuWdH%2FSvWgKtiwla3JLko716f2b4gp%2FDA%2FJIS7w7d7kwcsr4drdjPtAFVS%0Aslme5LnQ89%2FnD%2F7d%2BMS5EHKBCQRfz5eeLjJ1js%2BaWNJXMX43AYGyZm0pGrFmCW3R%0AbpD0ufovARTFXFZkAdl9h6g4U5%2BLXUZtXMYnhIHUfoyMo5tS58aI7Dd8KvvwVVo4%0AchDYABPPTHPbqjc1qCmBaZx2vN4Ye5DUys%2FvZwP9BFohFrH%2F6j%2Ff3IL16%2FRZkiMN%0AJCqVJUzKoZHm1Lesh3Sz8W2jmdv51b2EQJ8HmA%3D%3D%0A-----END%20CERTIFICATE-----%0A
Note that the url encode must include a newline character at the end (\n = %0A)
You can bypass the CA check (not secure) by setting the MQTTCA to empty:
MQTTCA
Limitations
Firmware updates only work if there is a connection to HAM Cloud. In case you need to update the firmware when only having an MQTT connection, this will not work.
The topics that the devices publish to are not configurable. Client id is HAM<FAMILY>h<SERIAL>t<TIMESTAMP>
There is no access control applied from the device side, it will push all state and execute all commands. Proper permissions should be configured with Access Control Lists on your MQTT server.