ioBroker.repositories

This is a GitHub project for storage of the latest and stable repositories.

!last refresh beta !last refresh stable

Update of the version in STABLE repository

1. Be sure that the version is tested in forum by users, or you fix the critical bug with that.
2. Delete the versionTime, if exists

Add a new adapter to the BETA (latest) repository

1. Fork this repo and clone your fork
2. Run npm i
3. Run npm run addToLatest -- --name --type

1. Push a commit with the changes to sources-dist.json
2. Create a PR

Add a new adapter to the BETA (latest) repository (web frontend)

1. Go to iobroker.dev
2. Log in with GitHub
3. Open the new adapter
4. Click on manage
5. Click on the action "ADD TO LATEST"

Requirements for an adapter to get added to the BETA (latest) repository

1. Your GitHub repository must have the name - ioBroker.. B is capital in "ioBroker", but in the package.json the name must be low case, because npm does not allow upper case letters. Your repository must have "topics". Add these with Manage topics.
2. Do not use in the title the words ioBroker or Adapter. It is clear anyway that this adapter is for ioBroker.
3. title in io-package.json (common) is simple short name of adapter in english. titleLang is object that consists short names in many languages. Lang ist not german Länge, but english LANGuages.
4. Adapter needs to have a README.md with description, detail information and changelog. English is mandatory. Other languages are welcome. See Example of README.md.

1. Adapter must have a predefined license.
2. Please remove www, widgets and docs directories (admin/tab_m.html, admin/custom_m.html) if not used.
3. Adapter needs to have at least Adapter basic testing (installing, running) using GitHub actions. More information in Forum from apollon77 (Just take from other adapters the samples)
4. Define one of the types in io-package.json. See details here
5. Define one of the connection types (if applied) in io-package.json. See details here
6. All states must have the according valid roles (and not just "state")
7. Include author in io-package.json and authors in io-package.json. See here.
8. Adapter needs to be available as package on npmjs.com. See How to publish on npm
9. iobroker organisation must be added as an owner to npm package. Why and how to do that.
10. Add your adapter into the list (first latest and after that into stable, when tested).

1. No new adapters will be accepted to repo without admin3 Configuration dialog. Admin2 dialog is optional!
2. Port attribute must have name port.
3. Check and follow the coding best practices listed below.

Development and Coding best practices

• Best use the adapter creator (https://github.com/ioBroker/create-adapter) or get a fresh relevant version from the Template Repository (https://github.com/ioBroker/ioBroker.template) to start coding to always get the latest basic version and also updates. You should not always copy basic files from former adapters!
• Do not copy a package.json or io-package.json after an installation because some fields might have been added on installation! e.g. io-package with common.installedFrom eds to be removed
• Use the Adapter Checker and fix all issues shown there: https://adapter-check.iobroker.in/
• Respect Object and state definitions, types and roles. Values not defined here must not be used. Discussions about missing roles or types are welcome:

• Only commit .vscode, .idea or other IDE files/helper directories to GitHub if there is a need to. This is to prevent the other user's settings from interfering with yours or make PRs more complex because of this.
• If you do not need stateChange/objectChange/message please do not implement it
• if you need to store passwords, please encrypt them. This can be done by just configuration:

• use jsonConfig for adminUI unless there is a special need to use REACT. Use i18n file based translation if possible.
• Do not use an adminTab unless functionality cannot be provided otherwise. Discuss with core team (@Apollon77) before implementing it to avoid later review discussions.
• add all editable fields from index_m.html to io-package.json native with their default values
• You need to make sure to clean up ALL resources in unload. Clear all Timers, Intervals, close serial ports and servers and end everything. Else this will break the compact mode (or also see the next point!)
• Use adapter.setTimeout/setInterval and corresponding clear Methods to create timers and intervals that are automatically cleaned up when the adapter gets unloaded and make sure to not start new timers/intervals after adapter is stopped already. This can help in many cases and is near to a drop-in replacement for Timers from Node.js (but it is NOT an object, so the methods on Timer objects will not work!)
• Please test in compact mode! Especially starting, running, stopping adapter and verifying that nothing runs any longer and no logs are triggered and also a new start works.
• Be careful with setObject because it overwrites the object and (especially in js-controller < 2.2) custom settings like history may be removed by this! Use setObjectNotExists or read the object to detect if it exists and use extendObject to update.
• get familiar with the ack concept of ioBroker. Adapters normally set all "final" values with ack=true and these are mostly ignored in onStateChange handlers. ack=false are commands that normally are handled by Adapters.
• Do not use process.exit() because this breaks compact mode. Use adapter.terminate().
• If you consider using a scheduling library in conjunction with external/cloud services, then consider the potential consequences! If your adapter becomes successful, then all users will do their calls to the external service in the exact same second. This can become a DOS stile "attack" to that server with bad consequences. Additionally, to that using a Scheduling library just to implement intervals is overkill :-) setInterval/setTimeout should be completely sufficient AND has a good side effect that requests are not done all at the same second, but start when the adapter starts.
• When using Intervals together with external communication, think about timeout and error cases - an interval triggers the next call also if the last has not finished. So requests might pile up and you DoS (Denial of Service) the external API. A better practice might be to use setTimeout and set at the end of one call for the next call
• If you use connections to other systems (Websockets, MQTT, TCP, Serial or other) please also implement the info.connection state (directly create objects by including in io-package) and set the connection value accordingly. Using this enables Admin to differentiate the status between green (ok, running), yellow (basically running but not connected) and red (not running).
• Consider and understand the asynchronous nature of JavaScript and make sure to know what will happen in parallel and what makes more sense to be sequential! It is ok to use callbacks or Promises/async/await - the later makes it easier to understand and control how your code really flows.
• Consider using ESLint or other JavaScript code and type checker to see errors in your code before releasing a new version. Use @iobroker/eslint-config to setup lint and prettier.
• Please activate adapter testing with at least package- and integration-tests on GitHub Actions
• The adapter testing using GitHub Actions is not for us - it is for you! Please check it after pushing changes to GitHub and before telling it to users or publishing an NPM package. If testing is "red," you should check the testing log to see what is broken.
• If you like to increase testing, you can start implementing adapter-specific tests that always run when you push changes to GitHub.
• You can/should use https://translator.iobroker.in/ to auto translate all relevant texts into all necessary languages by providing the English text
• If an adapter instance wants to generate an object structure, it should use objects from the type device, channel or folder to define substructures and provide objects of type state only on the last "level". Different levels can be separated by a ".". An object of the type "state" should never have more objects below it. The allowed fields for the relevant object types are documented in https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/objectsschema.md#core-concept
• If an adapter opens a port or bind socket to some IP-address, the attributes must be called port and bind (v6bind for IPv6).
• If an adapter connects to some IP-address, the IP attribute may be not called bind (use ip for that).

Add a new adapter to the stable repository

1. Fork this repo and clone your fork
2. Run npm i
3. Run npm run addToStable -- --name --version

1. Push a commit with the changes to sources-dist-stable.json
2. Create a PR

Requirements for an adapter to get added to the stable repository

Additionally, to all above listed points:

1. The adapter must have been added to the latest repository previously.
2. Forum thread with a question to test the adapter.
3. Some feedback on forum.
4. Important Discovery function! If a device can be found automatically (USB, IP), it should be implemented in the discovery adapter after (Discovery PR will be merged after stable acceptance).

Common Rules and Requirements for Commercial Adapters Requiring a License

For an optimal experience, it is recommended to procure licenses through the official ioBroker Website. The ioBroker GmbH facilitates license management and provides secure components for seamless integration into the adapter. In return for this service, a standard share of 30% of revenues is remitted to ioBroker GmbH. For further information or inquiries, please reach out to [email protected].

In cases where purchases are managed by the developer directly, and the adapter is intended for inclusion in the repository, a service fee of typically 15% of the revenue is applicable. For details and negotiations regarding this arrangement, please also contact [email protected].

How-to

How to publish on npm

https://docs.npmjs.com/getting-started/publishing-npm-packages

Add an owner to a packet

There is no problem with the GitHub repository. We can just fork it and maintain it in our organization, but the situation with npm is different.

If some name is blocked (e.g., iobroker.rpi) we cannot publish the changed adapter under the same name; we must change the name to e.g., iobroker.rpi2.

Then we must change the ioBroker repositories, and the user must install the new adapter and migrate the old settings and objects into the new adapter.

This is not suitable.

Because of that, we ask you to give ioBroker organisation publish rights to update the npm package. We will use it only in emergency or if the author does not react to our requests.

Please just add bluefox as an owner.

npm owner add bluefox iobroker.

Attention: bluefox must accept the invite. This might last a day or two. So please be patient until the invite has been accepted. If the invite expires, please retry (send a second invite).

Example of README.md

https://github.com/ioBroker/ioBroker.admin/blob/master/README.md

Much better is to write documentation separately for every language like here:

https://github.com/ioBroker/ioBroker.admin/blob/master/io-package.json#L171

and the files are here https://github.com/ioBroker/ioBroker.admin/tree/master/docs

And make the link in your readme file to these files, like here: https://github.com/ioBroker/ioBroker.javascript/blob/master/README.md

Licenses

• MIT (used for most of the adapters and core)
• Apache 2.0
• CC-BY
• OFL-1.1
• EPL
• LGPL
• GPLv3
• GPLv2
• CC-BY-NC
• CC-BY-NC-SA

Of course, you can add your own licenses, even WTFPL.

You must, of course, take in count the licenses of components that are used in your adapter. E.g., if you use the main packet under GPLv2 license, you cannot make CC-BY-NC from that.

Testing

Types

• alarm - security of home, car, boat, ...
• climate-control - climate, heaters, air filters, water heaters, ...
• communication - deliver data for other services via RESTapi, websockets
• date-and-time - schedules, calendars, ...
• energy - energy metering
• metering - other, but energy metering (water, gas, oil, ...)
• garden - mower, springs, ...
• general - general purpose adapters, like admin, web, discovery, ...
• geoposition - geo-positioning. These adapters deliver or accept the position of other objects or persons.
• health - heart pulse, blood pressure, body weight, ...
• hardware - different multipurpose hardware, arduino, esp, bluetooth, ...
• household - vacuum-cleaner, kitchen devices, ...
• infrastructure - Network, printers, phones, NAS, ...
• iot-systems - Other comprehensive smart home systems (software and hardware)
• lighting - light
• logic - rules, scripts, parsers, scenes, ...
• messaging - these adapters send and receive messages from message services: telegram, email, WhatsApp, ...
• misc-data - export/import of some unsorted information, contacts, system info, gasoline prises, share curses, currents (EUR=>USD), ...
• multimedia - TV, AV Receivers, TV play boxes, Android/Apple TV boxes, multiroom music, IR controls, speech input/output, ...
• network - ping, network detectors, UPnP, ...
• protocols - Communication protocols: MQTT,
• storage - logging, data protocols, SQL/NoSQL DBs, file storage, ...
• utility - different help adapters. Like backup, export/import
• vehicle - cars
• visualization - visualisation, like vis, material, mobile
• visualization-icons - icons for visualization
• visualization-widgets - iobroker.vis widgets
• weather - weather info, air quality, environment statistics

Connection types

Define connectionType in common part of io-package.json as:

• local - if the communication with the device does not require cloud access.
• cloud - if the communication is via cloud.

• poll - Querying the status means that an update may be noticed later.
• push - ioBroker will be notified when a new status is available.
• assumption - The status of the device cannot be determined. ioBroker takes status based on the last ioBroker command.

Defined categories for non-repo adapters

• pilight - iot-systems
• samsung2016 - multimedia
• viessmann - climate-control
• vuplus - multimedia

Authors

• https://github.com/ioBroker/ioBroker.template/blob/master/JavaScript/package.json#L5 (Only one author)
• https://github.com/ioBroker/ioBroker.template/blob/master/JavaScript/package.json#L9 (Many contributors)
• https://github.com/ioBroker/ioBroker.template/blob/master/JavaScript/io-package.json#L32 (Same here, but you can set many authors/contributors if desired)

Samples

"admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "type": "general"
  },

For stable (sources-dist-stable.json):

"admin": {
    "meta": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/io-package.json",
    "icon": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/admin/admin.png",
    "type": "general",
    "version": "2.0.7"
  },

Note: stable always has a specific version.

Automatic pull request checker

• Detect which adapters are changed by analyzing the diff of changed files (See detectAffectedAdapter in lib/check.js)
• Run an adapter checker from @iobroker/repochecker for each changed adapter.
• Add the comments to PR with the results of the checks.

Issues to move the latest version of adapter to stable

• If the latest version is good enough for stable and will create an issue if yes (See lib/readyForStable.js)

How is the repository built?