Repositories for ioBroker project
This is GitHub project for storage of latest and stable repositories.
versionTime
, if existsnpm i
npm run addToLatest -- --name <adapter-name> --type <adapter-type>
<adapter-name>
with your adapter's name (without 'iobroker.' prefix) and <adapter-type>
with the adapter type)sources-dist.json
Already required for the latest repository
Your GitHub repository must have the name - ioBroker.<adaptername>
. 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
.
Do not use in the title the words ioBroker
or Adapter
. It is clear anyway that this adapter is for ioBroker.
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
.
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.
In README.md
, there must be a link to the device or the manufacturer's website. Devices must have a photo. Services do not require a photo, but are still welcome.
Adapter must have a predefined license.
Please remove www
, widgets
and docs
directories (admin/tab_m.html
, admin/custom_m.html
) if not used.
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)
Define one of the types in io-package.json
. See details here
Define one of the connection types (if applied) in io-package.json
. See details here
All states must have the according valid roles (and not just "state")
Include author
in io-package.json
and authors
in io-package.json
. See here.
Adapter needs to be available as package on npmjs.com
. See How to publish on npm
iobroker
organisation must be added as an owner to npm
package. Why and how to do that.
Add your adapter into the list (first latest and after that into stable, when tested). Examples of entries you can find here.
No new adapters will be accepted to repo without admin3
Configuration dialog. Admin2
dialog is optional!
Port attribute must have name port
.
Check and follow the coding best practices listed below.
Note: you can watch the video about it (only german) on YouTube
Note: There is a helper https://adapter-check.iobroker.in/ to check many points automatically. Just place your GitHub adapter repo there, e.g. https://github.com/ioBroker/ioBroker.admin
and press enter or on the check button.
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.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.stateChange/objectChange/message
please do not implement itio-package.json
in encryptedNative
. Additionally, please also protect the access to this field by also providing protectedNative
(see e.g. https://github.com/TA2k/ioBroker.psa/blob/master/io-package.json#L81-L82)js-controller >= 3.0.0
and admin >= 4.0.9
(Admin needs to be a globalDependency
, see https://github.com/TA2k/ioBroker.psa/blob/master/io-package.json#L75-L80 and https://github.com/TA2k/ioBroker.psa/blob/master/io-package.json#L70-L74)index(_m).html
and in main.js
you can just convert to this by removing the extra encrypt/decrypt usages in all places and do the above.index_m.html
to io-package.json
native
with their default valuesunload
. Clear all Timers, Intervals, close serial ports and servers and end everything. Else this will break the compact mode (or also see next point!)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!)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.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.process.exit()
because this breaks compact mode. Use adapter.terminate()
if the method is available.setTimeout
and set at the end of one call for the next callinfo.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).callbacks
or Promises/async/await
- the later makes it easier to understand and control how your code really flows.port
and bind
(v6bind
for IPv6).bind
(use ip
for that).npm i
npm run addToStable -- --name <adapter-name> --version <stable-version>
<adapter-name>
with your adapter's name and <stable-version>
with the version that should be added to the stable repo)sources-dist-stable.json
Additionally, to all above listed points:
ioBroker GmbH sponsors all infrastructure and services necessary for the smooth functioning of the ioBroker world. This encompasses the repository, central components, and platforms such as the Forum. While the usage of open-source "non-commercial" adapters is entirely free, the scenario changes when adapters necessitate a purchase.
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].
https://docs.npmjs.com/getting-started/publishing-npm-packages
We are really happy that other developers are contributing to ioBroker. But some of them with the time lost the enthusiasm and stopped support and maintaining the adapter.
There is no problem with GitHub repository. We can just fork it and maintain it in our organisation, 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 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.
To add the ioBroker organisation to npm packet, you must write the following after the packet is published:
npm access grant read-write iobroker:developers iobroker.<adaptername>
If the command does not work, just add bluefox
as an owner.
npm owner add bluefox iobroker.<adaptername>
Attention: bluefox must accept the invite. This might last a day or two. So please be patient until the invite has been accepted. If invite expires, please retry (send a second invite).
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
The following licenses are used now in ioBroker project:
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
You can choose the suitable license here: https://ufal.github.io/public-license-selector/
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.
The Adapter Creator will create all needed files and deps for the testing, see also https://github.com/ioBroker/ioBroker.example/tree/master/JavaScript/test . Tests are then run by GitHub Action (also pre-generated)
The io-package.json
must have an attribute type in common part.
An example can be seen here:
alarm
- security of home, car, boat, ...climate-control
- climate, heaters, air filters, water heaters, ...communication
- deliver data for other services via RESTapi, websocketsdate-and-time
- schedules, calendars, ...energy
- energy meteringmetering
- 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 multi-purpose hardware, arduino, esp, bluetooth, ...household
- vacuum-cleaner, kitchen devices, ...infrastructure
- Network, printers, phones, NAS, ...iot-systems
- Other comprehensive smarthome systems (software and hardware)lighting
- lightlogic
- 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, systeminfo, gazoline prises, share curses, currents (EUR=>USD), ...multimedia
- TV, AV Receivers, TV play boxes, Android/apple TV boxes, multi-room 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/importvehicle
- carsvisualization
- visualisation, like vis, material, mobilevisualization-icons
- icons for visualizationvisualization-widgets
- iobroker.vis widgetsweather
- weather info, air quality, environment statisticsYou can see the types of existing adapters here and try to find the similar one.
If your adapter controls some device/car/house the adapter could be connected with various methods and receive data via different protocols.
Define connectionType
in common
part of io-package.json
as:
local
- if the communication with device does not require cloud access.cloud
- if the communication is via cloud.Define dataSource
in common
as:
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 last ioBroker command.pilight
- iot-systemssamsung2016
- multimediaviessmann
- climate-controlvuplus
- multimediaPlease define the following attributes in package.json
:
For latest (sources-dist.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"
},
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.
On every pull request to the repository, the GitHub Action will be triggered (see check.yml ). It will check the following things:
detectAffectedAdapter
in lib/check.js)@iobroker/repochecker
for each changed adapter.Every night the GitHub Action will be triggered at 3:15 (see stable.yml ). It will check the following things:
The repository is build executing npm run build
. However, this is currently only done on a dedicated server running on AWS.
However, before build the repository is pulled and thus uses the code from the repository. Hence, modifications how the repo is
built should be made against this repository.