This is a complete rewrite of the code I released here a few years ago; it covers much the same ground, but is now based on Pydantic data models.

For now: update with: pip install git+git://github.com/eykamp/thingsboard_api_tools.git --upgrade

Motivation

Thingsboard offers their own Python API, which seems to be autogenerated by Swagger. I have found it difficult to work with, so I reimplemented a small subset of the API that I found useful for my projects, mostly centered around Customers, Devices, and Dashboards. This API does things that are not straightforward to do through the API, such as retrieve the public URL for a dashboard, but there is a lot that it does not do.

Future

My focus on this project is my own uses, and I will attempt to maintain this into the future, but no promises. Please feel free to fork or submit pull requests. I make no promises about maintenance beyond what I need for myself, and I would welcome other maintainers to join me. I am open to any suggestions or feedback.

Testing strategy

Most of the core code has test coverage. The tests are designed to run on any Thingsboard instance, but generally assume the presence of some customers, devices, and/or dashboards. I use demo.thingsboard.io for my tests, but this does not let me test all things because the accounts you can create there are limited to user accounts. The API has a few functions related to tenants, for example, which cannot be tested with a test account at demo.thingsboard.io. Those tests are designed to fail gracefully. All test objects are (or should be) named with a __TEST__ prefix to make it easier to identify them if things go wrong.

How to help

I welcome PRs or assistance maintaining and expanding the project. I ask that any new functionality adhere to the code style (especially the use of type hints), and include test coverage. All tests should clean up after themselves. Luckily, on a project like this, tests are relatively easy.

A few quirks

• We use name throughout, whereas Thingsboard generally (but not always) uses title. They are the same, but I like name.

• Dashboards in Thingsboard are stored as a giant monolith of json. The API offers no tools for manipulating this -- it the server just acts as a datastore for the front-end code. This API models some of the internals of dashboards, which makes it possible to copy them and change the devices associated with different widgets. This code is inherently fragile, and is limited to my own reverse-engineering of selected dashboard objects.

Normally, when you ask the API for a dashboard, you get back all the metadata (name, user, etc.) but not the JSON monolith. I call that a DashboardHeader. You can then request that monolith, and I call the Dashboard with it's widget configuration a Dashboard. It's a bit wierd, but it reflects how Thingsboard works.

Note also that, as of this writing, the type hinting style straddles two eras. That will likely get cleaned up over time.

Root object

The root object is called TbApi. You instantiate that with your credentials, and you can use that to create or retrieve other objects.

Examples

There are tons of simple examples of how to to use this library in the test code. Here is one quick taste:

    # Create yourself a demo account: https://demo.thingsboard.io/signup
    mothership_url = "http://demo.thingsboard.io:8080"
    thingsboard_username = "your_username"
    thingsboard_password = "your_password"

    tbapi = TbApi(mothership_url, thingsboard_username, thingsboard_password)   # root object

    device = tbapi.get_device_by_name("ESP8266 Demo Device")        # In the default demo dataset
    telemetry = device.get_telemetry()
    print(telemetry)