The Things Network
The The Things Network integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] connects The Things Network or your own The Things Stack server to LoRaWAN. Separate device integrations turn readings from your LoRaWAN sensors into entities you can use in dashboards and automations.
For sensors based on stored, decoded payload fields, use The Things Network (Cloud Storage).
Prerequisites
- An application with registered devices in The Things Network or The Things Stack.
- A gateway within range that forwards your devices’ traffic to that network.
- An API key with access to the application.
To create an application API key:
- Open your application in The Things Network Console, or your server’s console.
- Select API keys > Add API key.
- Enter a name, such as
Home Assistant, and grant these individual rights:- View devices in application.
- Read application traffic (uplink and downlink).
- Write downlink application traffic, if you want to send commands through a compatible device integration.
- Create the key and copy it. The console only shows it once.
See The Things Stack API-key instructions for more details. An application API key gives access to that application only.
Register devices using their device catalog entries so Home Assistant can identify their brand and model. Entity support depends on the corresponding LoRaWAN device integration. A payload formatter and the Storage Integration are not required.
Configuration
To add the The Things Network hub to your Home Assistant instance, use this My button:
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select The Things Network.
-
Follow the instructions on screen to complete the setup.
Select your region, enter the API key, and choose the applications to connect. Home Assistant checks the key before showing the application list.
Select the region in your console URL: Europe (EU1), North America (NAM1), or Australia (AU1). The default is Europe (EU1). Select Custom server for another The Things Stack deployment.
The key created above. It needs device-read and traffic-read permissions for every selected application.
Shown for Custom server. Enter the API server address, including the scheme and port, such as https://thethings.example.com:8884. The standard region choices fill in the server addresses automatically.
Shown for Custom server. Enter its API server address if it differs from the Application Server. Leave it empty to use the same address.
Supported functionality
This integration does not create entities itself. It provides the connection to your applications. When a supported device appears, Home Assistant shows the matching LoRaWAN device integration in the Discovered section on Settings > Devices & services. That device integration creates the entities.
Data updates
Device readings arrive through live event streams. Changes to the device list are detected through server events and a check every 30 seconds. Home Assistant reconnects if the connection is interrupted.
Known limitations
- Historical readings are not fetched from storage. After a restart or reconnection, wait for the device’s next transmission.
- Each application can belong to only one connection for the same Identity Server.
- Applications must provide decrypted payloads. Applications configured to skip payload decryption are not supported.
Troubleshooting
Cannot connect to The Things Stack
Symptom: Cannot connect to The Things Stack
Description
The API server address and port may differ from the web console address.
Resolution
Check that the selected region matches your application and that Home Assistant can reach the server. The Things Network uses port 8884. For a custom deployment, check the API server address and port with your server administrator.
API key rejected or no applications available
Symptom: API key rejected or no applications available
Description
API keys are limited by their permissions and scope. An application key only exposes its own application.
Resolution
Check that the key has not expired or been revoked and has the permissions listed under Prerequisites. If Home Assistant asks you to reauthenticate, enter a replacement key with access to the same applications.
A device has no entities or readings
Symptom: A device has no entities or readings
Description
Entities require a compatible device integration and new uplinks. Stored readings are not replayed.
Resolution
Check that the device belongs to a selected application, has a DevEUI, and uses the correct catalog brand and model. Add the compatible LoRaWAN device integration when discovered.
Check the device’s live data in the server console. If no uplinks appear there, check the device’s network settings and gateway coverage. If uplinks appear, wait for a new transmission while Home Assistant is connected.
Removing the integration
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- Next to the entry you want to remove, select the three dots
menu. Then, select Delete. - Depending on the integration, the entries are listed under one of the following headings:
- Devices
- Hubs
- Services
- Integration entries
- Depending on the integration, the entries are listed under one of the following headings:
- To confirm, select Delete.
- Home Assistant also deletes the devices and entities of the entry.
- If Home Assistant asks you to restart, restart Home Assistant.
- If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.
- If you keep them, Home Assistant uses them automatically when you add the integration again.
- To delete them later, refer to Deleting application credentials.
Removing the connection stops updates from its applications. Your applications, gateways, and devices remain registered on the server. You can delete the API key in the server console if it is no longer used.