When to make a platform, and when to make a stand-alone component?

I have a scooter from NIU that has an app. I’ve previously done some testing in reverse engineering this app and I’ve come as far as getting charge-status and some other stuff from the api. It’s a rather simple web-api rest interface.

However, my question is more of a structural one. The login requires username/phonenumber and password. And currently I have enough reverse engineered to create a sensor (current charge), a binary sensor (is charging), a location (scooters current gps coordinates)… So should there be a platform on top? And how do I implement this in the best way? (I’m not a python dev originally, all reverse engineering is done in nodejs)

It sounds like you want to create an integration. An integration can provide platforms to work with existing components.

Think of it this way. A “component” is a piece of code that creates entities of a particular “domain” and provides the “high level” implementation for that domain, such as its services, common algorithms, etc. E.g., the light component creates and manages light entities, registers the services for turning them on and off, provides algorithms for converting between rgb, xy_color, etc.

But the component typically needs another piece of code that understands the specifics of a particular “type” of entity. E.g., for Z-Wave lights there is a piece of code that knows how to get the status of Z-Wave lights, turn them on and off, etc. This piece of code is referred to as a “platform”, and works in conjunction with the generic component code to complete the implementation.

As you might imagine, components work with multiple platforms, where the component provides the common, high level implementation, and each platform provides the specifics for a particular type of device.

Integrations provide one or more platforms for a particular type of device, depending on what makes sense. E.g., the amcrest integration provides a camera platform, a switch platform, a binary_sensor platform, and a sensor platform. Each platform works with the corresponding component.

It sounds like in your case you should create an integration that provides binary_sensor, device_tracker and sensor platforms. And given a username/phonenumber & password needs to be entered, it should probably also provide a config flow.

If you haven’t already, you should read up on the developer docs, especially the sections on architecture and the backend. And be aware this project is still very much a work in progress, where major changes are still happening, and the documentation lags a bit. Although you definitely should read the docs, you should also browse the code looking at examples of various integrations.

Good luck!


I also have a NIU scooter and it will be nice if it will be integrated. Someone already reversed the app and found out the api, here are some .py and .php implementations, if someone knows .py i think it can be integrated following this files: