Connect to Devices Using the Python SDK
This guide provides step-by-step instructions for using ngrok as a device gateway. This example shows you how to embed connectivity into an application using ngrok's Python SDK to access an API running on an IoT device. All the Python code in this example is available in the ngrok-samples/ngrok-python-iot-agent repo.
Prerequisites
To use the sample application, you need the following prerequisites on the device or device gateway you wish to connect to:
- Python 3.11
- venv or another Python virtual environment manager
Get an ngrok API Key
Create an ngrok API key using the ngrok dashboard. Make sure you save the API key before you leave the screen because it won't be displayed again.
Create a custom wildcard domain
Create a custom wildcard domain, which will allow you to create endpoints and receive traffic on any subdomain of your domain.
For example, you might create *.sitea.{YOUR_DOMAIN}
. You would then be able to create endpoints
on device342.sitea.{YOUR_DOMAIN}
and device896.sitea.{YOUR_DOMAIN}
without having to reserve them individually.
It can be helpful to create a separate subdomain for each site you wish to connect to.
Run the following command, substituting your API key for {API_KEY}
and your domain for {YOUR_DOMAIN}
:
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"domain":"*.sitea.{YOUR_DOMAIN}","region":"us"}' \
https://api.ngrok.com/reserved_domains
You should receive a 201
response similar to the following:
{
"id": "rd_2euR3S7Mt07gRC6NlVGcXtghElK",
"uri": "https://api.ngrok.com/reserved_domains/rd_2euR3S7Mt07gRC6NlVGcXtghElK",
"created_at": "2024-04-10T12:31:16Z",
"domain": "*.sitea.configurable-domain.com",
"region": "",
"cname_target": "mwz4q7fiabfcxbfy.4wsgv9l5wfesschhy.ngrok-cname.com",
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"certificate": null,
"certificate_management_policy": {
"authority": "letsencrypt",
"private_key_type": "ecdsa"
},
"certificate_management_status": {
"renews_at": null,
"provisioning_job": {
"error_code": null,
"msg": "Managed certificate provisioning in progress.",
"started_at": "2024-04-10T12:31:16Z",
"retries_at": null
}
},
"acme_challenge_cname_target": "f7ekwqdb.acme-challenge.ngrok-dns.com"
}
You'll need values from the response in the next section.
Update DNS records
Next, add two CNAME
records to your DNS provider's registry, providing values from the previous response.
Add a CNAME record for the wildcard subdomain you just created.
Then add another record for the
ACME (Automated Certificate Management Environment)
validation. For the record, enter _acme-challenge.{SUBDOMAIN}
, and use the value of the acme_challenge_cname_target
property from from previous response for the value. For the example above, the record name would be
_acme-challenge.sitea
.
Verify DNS
Use the ngrok dashboard to verify that you’ve configured DNS correctly.
- Login to the ngrok dashboard.
- Click Domains in the left-hand navigation menu.
- Click on your wildcard domain under Domain.
- Click 2 targets next to DNS Targets in the panel displayed on the right-hand side of the screen, as denoted by the arrow in the screenshot below.
- Click Check Status, as denoted by the arrow in the screenshot below.
- You should see a successful response similar to the screenshot below.
Create a bot user
You’ll create a bot user so that in the next section, you can create an agent authtoken independent of any user account. A bot user does not belong to a particular user account. Run the following command to create a new bot user, providing your API key and a description:
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"name":"new bot user from API"}' \
https://api.ngrok.com/bot_users
You should receive a 201
response similar to the following:
{
"id": "bot_2fmwUXhnImKswMgZKCsx7cnbt2l",
"uri": "https://api.ngrok.com/bot_users/bot_2fmwUXhnImKswMgZKCsx7cnbt2l",
"name": "new bot user from API",
"active": true,
"created_at": "2024-04-29T19:39:36Z"
}
Create the agent authtoken
You should start each agent using a separate authtoken, and that token should belong to a bot user.
To create an authtoken, login to the ngrok dashboard and click Authtokens
under Tunnels, then click Add a Tunnel Authtoken.
For Owner, select the bot user you use created, and select bind:*.sitea.{YOUR_DOMAIN}
for the ACL Rules.
This ACL will allow an agent with the authtoken to create tunnels on any subdomain of sitea.{YOUR_DOMAIN}
.
Configure the sample agent
The sample application uses the ngrok Python SDK to embed connectivity directly into the application rather than using the standalone ngrok agent, the CLI, or the ngrok Kubernetes Operator. It serves a local REST API you can use to create, delete, and list tunnels.
Clone the repo
Clone the ngrok-samples/ngrok-python-iot-agent repo on the device or device gateway you wish to connect to.