Skip to content
  • There are no suggestions because the search field is empty.

Connect MQTT sensors to Humly Sensor Gateway

MQTT sensors publish their readings straight to the MQTT broker built into Humly Sensor Gateway (HSG). Each sensor gets its own login and its own topic. This article uses the Atlona AT-OCS-900N occupancy sensor as the example.

In this article

Before you start

  • HSG is set up and paired. See Humly Sensor Gateway - First-time setup.
  • The sensor is on the network and can reach the HSG server on port 1883.
  • You can sign in to the sensor's web page. On the Atlona AT-OCS-900N, open https://<sensor-ip> in a browser.

Using another MQTT sensor?

Tell us about it. Email support@humly.com with the brand, the model and whether it uses LoRaWAN or MQTT. Most LoRaWAN sensors work without changes. For other MQTT sensors, we can add support in an HSG update.

Step 1: Create the sensor's MQTT login

  1. In the HSG dashboard, go to Settings.
  2. Under MQTT sensor credentials, select the vendor, for example atlona.
  3. Click + Mint credentials.
  4. Copy the Username, Password and Topic prefix. HSG shows the password only once.

The MQTT credentials minted dialog showing the external ID, username, password and topic prefix

Create one login per sensor. The username and password are 16 characters long. That is the most the Atlona AT-OCS-900N accepts.

Step 2: Give the sensor a fixed address

A sensor that loses its network address stops sending data. Give it a stable address in one of two ways:

  • Keep Enable DHCP on, and add a DHCP reservation for the sensor's MAC address in your DHCP server. This is the easiest option.
  • Or turn Enable DHCP off and enter a fixed IP address, gateway, subnet mask and DNS server.

On the Atlona AT-OCS-900N, these settings are under Network. The page also shows the MAC address and has a Restart Device button.

The Atlona Network Configuration page with host name, DHCP, IP address, gateway, subnet mask and DNS fields

Give the HSG server a fixed address as well. Every MQTT sensor points at it.

Step 3: Set up MQTT on the Atlona AT-OCS-900N

Go to Protocols and scroll to MQTT Client. Fill in the settings below, then click Save.

The Atlona MQTT Client settings filled in for Humly Sensor Gateway

SettingValue
Enable MQTTOn
BrokerThe HSG server's IP address or host name
Port1883
Client-IDKeep the default, for example OCS-900N-0F22F6
Keep Alive60
Clean SessionTicked
Username / PasswordFrom step 1
AuthenticationTicked
Last Will SettingsLeave empty
Publish topic, MotionEnabled. <topic prefix>/motion. QoS 0.
Publish topic, LightDisabled. HSG does not use light readings.
Publish topic, TempEnabled. <topic prefix>/temperature. QoS 0.

For example, with the topic prefix sensor/1de6952c-0945-44fa-882a-537d7e454997, the motion topic is sensor/1de6952c-0945-44fa-882a-537d7e454997/motion. The topic must start with the exact prefix from step 1.

After you save, restart the sensor with Network > Restart Device. It then connects with the new settings.

Good to know

The same page has UDP, TCP and WebSocket settings. Those serve other systems, such as AV control. MQTT works alongside them, so you can leave them as they are.

Step 4: Choose when the sensor reports

The Atlona AT-OCS-900N only reports when something changes. Two settings under Sensors decide how quickly Humly sees a change.

Motion Sensor

  • Motion On Event: seconds of continuous motion before the sensor reports motion.
  • Motion Off Event: minutes without motion before the sensor reports that the room is empty.

The Atlona Motion Sensor settings with Motion On Event and Motion Off Event

A short Motion Off time frees a room quickly. A longer time avoids marking a room as empty when people sit still.

Ambient Temperature Sensor

  • The Events threshold is the temperature change that triggers a new reading. With 1 °C, the sensor reports only when the temperature moves by a full degree.
  • Lower the threshold, for example to 0.5, for more frequent temperature updates.
  • Keep the unit set to °C.

The Atlona Ambient Temperature Sensor settings with the event threshold

Step 5: Approve the sensor

The sensor appears on the HSG Sensors page as Pending. Until it sends its first reading, it shows awaiting first publish. Walk under the sensor to trigger a motion reading.

  1. Click Confirm on the sensor.
  2. Enter a display name, for example the room name. Click Confirm.
  3. Assign the sensor to a resource in Humly Control Panel.

The Confirm sensor dialog with a display name field

Good to know

Because the sensor only reports changes, a reading can be hours old in a quiet room. That is normal.

Change or remove a login

  • New password: On the Sensors page, use Regenerate password on the sensor. The username and topic stay the same. Enter the new password in the sensor and restart it.
  • Remove a sensor: Use Delete on the sensor. This also removes its MQTT login and unregisters it from Humly Control Panel.

If the sensor does not connect

  • The Logs page shows "not authorised" for the sensor. The username or password is wrong. Regenerate the password and enter it again.
  • The Logs page shows nothing from the sensor. Check that Enable MQTT is on and the broker address is right. Check that the sensor has a network address and can reach port 1883.
  • The sensor connects, but no sensor appears in HSG. The topic does not start with the topic prefix from step 1. Look for "unknown sensor" warnings on the Logs page.

MQTT traffic is not encrypted. Keep MQTT sensors and HSG on a trusted network.

More help: Humly Sensor Gateway - Troubleshooting.

Humly Sensor Gateway guide

Get started

Install and set up

Connect sensors

Manage and troubleshoot