Best practices for adapters
An adapter can run on other systems for years without anyone noticing. Much of what's described here only becomes apparent when it's missing. The points are ranked according to the hassle they prevent.
Don't start from scratch
The Adapter Creator generates a framework with the standard directory structure, tests, and translation files. It's not a beginner's tool, but rather the fastest way to create a structure that others will recognize. Additional tools are available under Custom Adapter .
For access to ioBroker always@iobroker/adapter-core Never use the databases directly.
Clean up when you finish
Every timer, subscription, and open connection is cleared when the instance is shut down. If this is neglected, the instance cannot be restarted cleanly, it consumes more memory with each restart, and eventually the user's system will crash.
This is the most common fault in adapters and the one that users find most difficult to find themselves.
Use access sparingly.
- Only query a device as often as its value actually changes. A counter reading does not require second-by-second resolution.
- Only write values when they have changed. Every write operation consumes resources and, if recording is enabled, memory.
- Create objects once, don't rewrite them on every run. Object and state are two different things; see JS controllers .
The user notices a wasteful adapter when their Raspberry Pi gets warm and the SD card dies.
Setting roles and units correctly
The role of a data point determines whether visualizations, voice assistants, and automatic device recognition can do anything with it.state It is allowed, but it is the answer for when you don't know any better.
Likewise,type ,unit ,min ,max ,read andwrite maintained. A data point without a unit is a meaningless number.
Protect secrets
Passwords and access keys should be encrypted and stored in the configuration.protectedNative Protected from other adapters. How this works is explained under Security .
Never write access data to the log, not even at this level.debug Excerpts from the minutes end up in forum posts.
Properly document everything
info This is for normal operation: start, stop, connection established or lost. Everything else belongs after.debug An adapter that writes a line every second during normal operation renders the log unusable for all others. See Logging for details.
Error messages are meant to tell you what to do.Error: undefined It doesn't help anyone.
Place files in the correct location
Your own files belong in the ioBroker file storage , not in a directory you created yourself under/opt/iobroker This is the only way they are included in a data backup and survive an update.
Translate
The text in the configuration interface and the names of the objects are translated. The translator takes an English text and outputs the other languages. See Translations for details.
Get tested
Automated tests catch precisely those errors that you wouldn't see during manual testing because your own device responds and your configuration is correct. See Testing adapters .
Before the adapter is released
The conditions for inclusion in the official repository, including category, connection type, and details in theio-package.json , are listed under Publish Adapters . The project maintains a list of requested adapters under AdapterRequests .