iobroker/adapter-core

Core module to be used in ioBroker adapters. Acts as the bridge to js-controller

ioBroker (windows installer)

Automate your life!

To install on Linux, just run: npx @iobroker/install

To install on Windows: mkdir C:\iobroker && cd C:\iobroker && npx @iobroker/install or use installer

See ioBroker documentation for more information

• ioBroker website
• Forum
• Requests for adapters

ioBroker is an integration platform for the Internet of Things, focused on Building Automation, Smart Metering, Ambient Assisted Living, Process Automation, Visualization and Data Logging.

Concept

ioBroker is not just an application, it's more of a concept and a database schema. It offers a very easy way for systems to interoperate. ioBroker defines some common rules for a pair of databases used to exchange data and publish events between different systems.

Databases

ioBroker uses "in memory" database to hold the data and saves it on disk with reasonable intervals. There are two types of storage:

• objects (meta/configuration information)
• states (values)

Objects and states can be stored in "in memory" or in Redis.

Redis is an in-memory key-value data store and also a message broker with publish/subscribe pattern.

It's used to maintain and publish all states of connected systems.

Adapters

Systems are attached to ioBrokers databases via so-called adapters, technically processes running anywhere in the network and connecting all kinds of systems to ioBrokers databases. A connection to ioBrokers databases can be implemented in nearly any programming language on nearly any platform, and an adapter can run on any host that is able to reach the databases via ip networking.

See the actual list of adapters on iobroker.net

Security

ioBroker is designed to be accessed by trusted adapters inside trusted networks. This means that usually it is not a good idea to expose the ioBroker databases, adapters or any smart home devices directly to the internet or, in general, to an environment where untrusted clients can directly access these network services. Adapters that offer services supposed to be exposed to the internet should be handled with care. You should always activate HTTPS and use valid certificates for web, admin if open it for internet or for example, use it with additional security measures like VPN, VLAN and reverse proxies.

Getting Started

Operating System and Hardware

ioBroker.js-controller should run on any hardware and OS that runs Node.js (ARM, x86, Windows, Linux, OSX).

ioBroker spawns a new Node.js process for every adapter instance, so RAM becomes a limiting factor. A single adapter's memory fingerprint is roundabout 10 to 60 MB.

Installation and first steps

• ioBroker Download

Community support

• Get help in the ioBroker Forums (english, german and russian languages)

Logos and pictures

All logos are protected by copyright and may not be used without permission.

Please request permission via [email protected]

Logos

License

This module is distributor under the MIT License (MIT). Please notice that other ioBroker adapters can have different licenses.

The MIT License (MIT)

Copyright (c) 2014-2024 bluefox [email protected], Copyright (c) 2014 hobbyquaker

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

adapter-core's Issues

start in compact mode no longer possible

When stating ke-contact Adapter in compact mode, I'm getting the error "Cannot start kecontact.0 in compact mode. Fallback to normal start: ENOENT: no such file or directory, open '/opt/iobroker/node_modules/iobroker.kecontact/node_modules/@iobroker/adapter-core/build/index.js'"
as suggested by @Apollon77 this issue is opened.
eMail-Adapter (1.2.2) still runs fine with compact mode.

setForeignState if value is from type object

@AlCalzone

As discussed in Telegram, here is the issue.

If I have a value of type object, then the value is not written when using the function await this.setForeignStateAsync(id, value, true);

If I use await this.setForeignStateAsync(id, {val: value, ack: true}); instead, the value is written

With js-controller 2.2.9 no error message is generated.

As discussed I test it with 3.x. Report me then again

FORBIDDEN_CHARS not defined in types

https://github.com/ioBroker/ioBroker.js-controller/blob/d2f418cbc196deaa10f018e08334ff083be28d7e/lib/adapter.js#L474

Update all dependencies and release 2.4.1

When I tried to do an npm update inside an adapter directory, it wouldn't update @types/iobroker.

Thus we should release a new version with all latest dependencies, even if we don't have any new features.

Export more Controller Libs

All from Libs dir:

• letsencrypt.js
• password.js
• session.js
• zipFiles.js

Enable Travis

@Apollon77 After I add travis.yml, can you enable the tests?

`adapter.delObject` has an option `{recursive: true}`

Error in PartialOtherObject.common TypeScript definition

        interface OtherObject extends BaseObject {
            type: 'adapter' | 'config' | 'enum' | 'group' | 'host' | 'info' | 'instance' | 'meta' | 'script' | 'user';
            common: OtherCommon;
        }
        interface PartialOtherObject extends Partial<Omit<OtherObject, 'common'>> {
            common?: Partial<ObjectCommon>;
        }

The common of a PartialOtherObjects should be of type Partial<OtherCommon> and not Partial<ObjectCommon>.

Missing TypeScript definition for EnumObject

In the TypeScript definition, enum objects are currently handled as OtherObject but enums require (at least) the members property, thus it would be good to have a definition for EnumObject (otherwise the compiler complains about the unknown members property.

Missing smartName in TypeScript definition

The iot adapter (and possibly others) uses the common.smartName property to know how the state should be named e.g. in Alexa.

smartName can be 'ignore' (special case: the state is to be ignored), a simple string or an object containing at least:

{
  byOn: boolean;
  en: string;
}

It is very much possible that there are more properties in the object.
You can find more infos here:
https://github.com/ioBroker/ioBroker.iot/blob/master/lib/alexaSmartHomeV2.js

Add typings for new methods

ioBroker/ioBroker.js-controller#407

ERESOLVE overriding peer dependency @iobroker/types

Looks like this change generates a lot of warnings: 75860ec

npm warn ERESOLVE overriding peer dependency
 
npm warn While resolving: @iobroker/[email protected]
npm warn Found: @iobroker/[email protected]
npm warn node_modules/iobroker.admin/node_modules/@iobroker/types
npm warn @iobroker/types@"6.0.0" from [email protected]
npm warn node_modules/iobroker.admin
npm warn iobroker.admin@"6.17.14" from the root projectnpm warn
npm warn Could not resolve dependency:
npm warn peer @iobroker/types@"^5.0.11" from @iobroker/[email protected]
npm warn node_modules/iobroker.admin/node_modules/@iobroker/adapter-core
npm warn @iobroker/adapter-core@"^3.1.4" from [email protected]
npm warn node_modules/iobroker.admin

adapter-core/package.json

Lines 82 to 84 in 10a74ef

	"peerDependencies": {
	"@iobroker/types": "^6.0.0"
	}

Readme changelog: Node 16+ should be mentioned

If it is correct, that (HGlab01/ioBroker.followthesun#566 (comment))
Adapter core 3.x.x is known to fail during installation on node 14 as npm 6 does not install peer dependencies. So this adapter reuired node 16 or newer
then it should be mentioned in 3.x changelog.

Custom object array results in errors for TS-validation

In situations were obj.common.custom is used TS-check results in error :

@AlCalzone

code examples :
https://github.com/iobroker-community-adapters/ioBroker.sourceanalytix/blob/master/main.js#L58-L63

Definitions for subscribe[Foreign]ObjectsAsync missing

Switch to ESLint and Prettier

See ioBroker/create-adapter#136 for a template

Typings admin5 common.states

Common.states is now allowed to be a string array, maybe also number @GermanBluefox ?

e.g.

	{
		_id: 'status',
		type: 'state',
		common: {
			name: 'Current status of wallbox',
			type: 'string',
			role: 'indicator.status',
			write: false,
			read: true,
			states: [
				'Available',
				'Preparing',
				'Charging',
				'SuspendedEVSE',
				'SuspendedEV',
				'Finishing',
				'Reserved',
				'Unavailable',
				'Faulted'
			]
		},
		native: {}
	},

Typings AdapterInstance strictObjectChecks

TS2339: Property 'performStrictObjectChecks' does not exist on type 'AdapterInstance '.

unfortunately I need to change it in the benchmark adapter

Expose new webServer and depricate letsEncrypt

Dependant on ioBroker/ioBroker.js-controller#2099

Try to infer object type from object itself if ID doesn't allow it

await this.setObjectNotExistsAsync(dp, {
	type: "state",
	// ^ This does not narrow the object type
	common: {
		name: common_name,
		role: common_role,
		type: common_type,
		unit: common_unit,
		// ^ Error here, but unit is allowed in a state
		read: common_read,
		write: common_write,
		def: common_def
	},
	native: {}
});

Utility methods taking an adapter instance cannot be called with adapter instance

Argument of type 'this' is not assignable to parameter of type 'AdapterClass'.
  Type 'ZWave2' is missing the following properties from type 'AdapterClass': _config, _options, startedInCompactMode, logList, and 112 more.

Typings: TS2339: Property 'tier' does not exist on type 'InstanceCommon'.

common.tier can be 1, 2, 3 number

Property 'from' does not exist on type 'Object'.

but it exist on every object, issue happens in onObjectChange(){}

Typing issues

• findObjectCallback - according to types, name is string but it should be stringOrTranslated
• Object/AnyObject always has a type, however this is not true for the _design/xy objects, they have no type but have property views e.g.

{
  "_id": "_design/chart",
  "language": "javascript",
  "views": {
    "chart": {
      "map": "function(doc) { if (doc.type === 'chart') emit(doc._id, doc); }"
    }
  },
  "from": "system.host.ubuntu.cli",
  "ts": 1644561649221,
  "acl": {
    "object": 1636,
    "owner": "system.user.admin",
    "ownerGroup": "system.group.administrator"
  }
}

• RmResult and thus RmCallback states there is a property isDir, code-wise it is never there.
• ReadDirResult states, that property stats is of type fs.Stats, sometimes objects db just returns an empty object, I assume that Partial<fs.Stats> would be a better fit
• ReadFileCallback/ReadFilePromise declare a property file but the property is called data code-wise
• StateCommon can basically have [other: string], or at least https://github.com/ioBroker/ioBroker.js-controller/blob/86e3a2e82e535713b07691b7cf4cd22f8119bcf1/packages/db-objects-redis/src/lib/objects/objectsInRedisClient.js#L51
  We should discuss this in ioBroker/ioBroker.js-controller#507
• On ReadFilePromise, mimeType can be undefined
• we should extend types of ReadDirCallback to ensure that the result is defined, if error is falsy, because code-wise it is
• StringOrTranslated proeprty en should not be optional if it is an object
• UnloadHandler states that there is always the argument callback however, we check if arg is there, else we await it because we assume it to return a promise
• Adapter.js sets binary: boolean on StateObject if it corresponding to a binary object.
• InstanceCommon can have restartSchedule: string (schedule)
• InstanceCommon can have property wakeup boolean
• InstanceCommon can have version string or maybe better type possible for semver
• In general we should check if InstanceCommon is not mainly a copy of AdapterCommon
• SetStateChangedCallback make err optional like on setStateCallback
• same for GetStateCallback, GetStatesCallback
• delBinaryState returns optional id as second CB parameter and is not a normal ErrorCallback
• AdapterCommon can have news as i18n object
• InstanceCommon has property logLevel but it should be loglevel
• AdapterObject can have dependencies and globalDependencies

Declare a module (or property of Adapter) that can be used by adapters, e.g. "system"

Currently, we have a lot of helper functions inside lib/tools.js from js-controller. Some of these are desirable to be used by adapters directly in the future, for example:

• getSystemNpmVersion
• createUuid
• the upcoming npmCommand (https://github.com/AlCalzone/ioBroker.js-controller/tree/tools-npmCommand) and its variants

while others should not be exposed to adapters. I propose that we add a clearly defined way to access these via adapters, which could be one of the following:

• A new property on the adapter instance, e.g. adapter.system, which has all these public utility methods
• Or another module we expose via utils.js which is included in every adapter. This has the advantage that we don't need an adapter instance and can do stuff during initialization.

This "system" module could just import and re-export some methods from tools.js. This way, the "external" names of methods could be kept the same while we're free to rename stuff in tools.js.

Took over from ioBroker/ioBroker.js-controller#252

Remove adapter.objects / adapter.states from TypeScript definitions

See ioBroker/ioBroker.js-controller#359

adapter.namespace needs a literal type, not `string`

Otherwise it cannot be used in object IDs to infer the object type

Provide a gulpfile to be imported in adapters

From ioBroker/create-adapter#73 (comment)

It could be exported similar to http://macr.ae/article/splitting-gulpfile-multiple-files.html (near bottom)
and imported like require('@iobroker/adapter-core/gulp/' + task)

add `defAck` property to StateCommon

Think about adding some kind of "Docker detection"

It might be useful to let adapters know that they are running inside a Docker container. There are some special things coming up when running ioBroker inside a Container.

Just some example use cases:

1. Running an adapter which uses multicast > if its working or not depends on the network configuration of the container > developer can add a hint and maybe a link for additional information at the adapter settings page
2. Backitup adapter > restoring only works when iobroker is stopped > it would be possible to add a docker specific start/ stop script to the adapter to get restore working in docker
3. Running yahka or z-wave adapter > adapters need some special settings (environment variables) in docker > developer can add a hint and maybe a link for additional information at the adapter settings page

How to determine if something is running inside a Docker container is shown here for example:
https://stackoverflow.com/questions/20010199/how-to-determine-if-a-process-runs-inside-lxc-docker

Cases 3 may also need a detection if the docker image is the official ioBroker docker image because the environment variables are defined within the image.
For this kind of detection it may work if I place some kind of identification file inside the docker image.

Any thoughts to this?

Regards,
André

Enable mocha tests on CI

Exposing controller tools install/uninstall npm and isDocker

expose https://github.com/ioBroker/ioBroker.js-controller/blob/fafabd20af76b3cae124318c8af3d3826d2979c3/packages/common/lib/common/tools.js#L3468-L3469

will close #ioBroker/ioBroker.js-controller#202

adapter.extendForeignObject TS validation fails for obj

In situations were obj.common.custom is used TS-check results in error :

@AlCalzone

code examples :

https://github.com/iobroker-community-adapters/ioBroker.sourceanalytix/blob/master/main.js#L608-L726

There should be an easier way to refer to the results of `ioBroker.SettableObjectWorker<ioBroker.StateObject>` etc

see title

TS-definition of getDevices returns different type then defined

The call for getDevices is described as follows:

adapter.getDevices((error: string | null, deviceList?: Array<GetObjectsItem<DeviceObject>>)

So the second argument of the callback would return a list of objecs that contain two attributes: id: string, value: DeviceObject.

However, in practice I get back only a List of DeviceObject. An extract from a project I currently work on contains:

this.getDevices((error, deviceList?: Array<any>) => {
	console.log(JSON.stringify(deviceList));
	if(deviceList) {
		deviceList.forEach((device: ioBroker.DeviceObject) => {
			this.registerPEHAdevice(device);
		});	
	}
});

In the debug-log-output I find from the console.log this:

[
    {
        "type": "device",
        "common": {
            "name": "tv"
        },
        "native": {
            "senderId": "1",
            "actorId_A": "ff80a902",
            "actorId_B": "ff80a900"
        },
        "from": "system.adapter.enocean_jobe.0",
        "ts": 1549936533169,
        "_id": "enocean_jobe.0.tv"
    }
]

step and chart is missing in type definitions, info is missing in documentation

Hi,

step is defined as a common attribute for states in schema:

common.step (optional) - increase/decrease interval. E.g. 0.5 for thermostat

See https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/objectsschema.md

Also chart is defined as object type in schema, but not included in definition:

chart - charts

Please integrate in type definitions.

"info" is defined as object in definitions, but missing in schema.md.

Please fix definitions or documentation :)

Thanks and regards,

Ralf

Property 'supportsFeature' and 'getPluginInstance' does not exist on type

		if (this.supportsFeature && this.supportsFeature('PLUGINS')) {
			const sentryInstance = this.getPluginInstance('sentry');
			if (sentryInstance) {
				sentryInstance.getSentryObject().captureException(error);
			}
		}

Fix getObjectView return types

design system gives objects
design custom gives common.custom
all others should be generic with any as a default

setObject etc. should not show an error if `obj.type` is `string` and the object satisfies any of the object types.

Allow different ID for read and write of aliases

ioBroker/ioBroker.javascript@89aaacb#r56527099

according to the docs the id can use different IDs for reads and writes.

Relevant section:

alias: {
            id: {
                read: 'state.id.to.read.from',
                write: 'state.id.to.write.to'
            }
            read: 'val * 10 + 1',
            write: '(val - 1) / 10'
        }

Adapter.terminate accepts any combination of reason and exit code

Upgrade @types/iobroker to 4.0

... once released

Offer decrypt method directly on adapter-code import

Should we offer the "tools.decrypt" directly on the adapter-core import object? Else it is needed to include tools ...

Ok normally noone should use/need it ... but ...

Async functions (promisifed versions) are not known by adapter-core

e.g. getStateAsync

GetStatesAsync() and GetForeignStatesAsync() can never return null

Please fix the type definition:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/cc28fa4757887547af26a768e7ace7d0d2939137/types/iobroker/index.d.ts#L1673

- type GetStatesPromise = Promise<CallbackReturnTypeOf<GetStatesCallback>>;
+ type GetStatesPromise = Promise<NonNullCallbackReturnTypeOf<GetStatesCallback>>;

getStates pattern might be more than just a string

https://github.com/ioBroker/ioBroker.socketio/blob/523a681cffc77847286cad5c274f038559f26718/example/conn.js#L1196
https://github.com/ioBroker/ioBroker.socketio/blob/523a681cffc77847286cad5c274f038559f26718/example/conn.js#L645

Types for @types/iobroker

Types for @types/iobroker

must be changed from

type ChownFileCallback = (err?: NodeJS.ErrnoException | null, entries?: ChownFileResult[], id?: string) => void;

to

type ChownFileCallback = (err?: NodeJS.ErrnoException | null, processed?: ChownFileResult[]) => void;

The types of 'common.type' are incompatible between these types.

Building the common object with :

                const common = {};
		common.name = stateAttr[name] !== undefined ? stateAttr[name].name || name : name;
		common.type = 'number';
		common.role = stateAttr[name] !== undefined ? stateAttr[name].role || 'state' : 'state';
		common.read = true;
		common.unit = stateAttr[name] !== undefined ? stateAttr[name].unit || '' : '';
		common.write = stateAttr[name] !== undefined ? stateAttr[name].write || false : false;

than having the extendObjectAsync function :

			await this.extendObjectAsync(stateName, {
				type: 'state',
				common
			});

Gives type check error :

As I give it the value "number", this check is wrong ?