1 | # Adapter-Core
|
2 |
|
3 | Core module to be used in ioBroker adapters. Acts as the bridge to js-controller.
|
4 |
|
5 | This replaces the `utils.js` included in the ioBroker template adapter.
|
6 |
|
7 | ## Usage
|
8 |
|
9 | 1. Add this as a dependency: `npm i @iobroker/adapter-core`
|
10 | 2. Replace
|
11 | ```js
|
12 | const utils = require(__dirname + "/lib/utils");
|
13 | ```
|
14 | with
|
15 | ```js
|
16 | const utils = require("@iobroker/adapter-core");
|
17 | ```
|
18 | 3. Create an adapter instance as usual:
|
19 | ```js
|
20 | // old style
|
21 | const adapter = utils.adapter(/* options */);
|
22 | // new style (classes). See https://github.com/ioBroker/ioBroker.template/ for a more detailed usage
|
23 | class MyAdapter extends utils.Adapter {...}
|
24 | ```
|
25 |
|
26 | ## Utility methods
|
27 |
|
28 | Compared to the old `utils.js`, some utility methods were added.
|
29 |
|
30 | ### `getAbsoluteDefaultDataDir`
|
31 |
|
32 | ```js
|
33 | const dataDir = utils.getAbsoluteDefaultDataDir();
|
34 | ```
|
35 |
|
36 | This returns the absolute path of the data directory for the current host. On linux, this is usually `/opt/iobroker/iobroker-data`
|
37 |
|
38 | ### `getAbsoluteInstanceDataDir`
|
39 |
|
40 | ```js
|
41 | // old style
|
42 | const instanceDataDir = utils.getAbsoluteInstanceDataDir(adapter);
|
43 | // new style (classes)
|
44 | const instanceDataDir = utils.getAbsoluteInstanceDataDir(this);
|
45 | ```
|
46 |
|
47 | Returns the absolute path of the data directory for the current adapter instance.
|
48 | On linux, this is usually `/opt/iobroker/iobroker-data/<adapterName>.<instanceNr>`
|
49 |
|
50 | ### `EXIT_CODES`
|
51 |
|
52 | ```js
|
53 | adapter.terminate(
|
54 | "for some reason",
|
55 | utils.EXIT_CODES.ADAPTER_REQUESTED_TERMINATION,
|
56 | );
|
57 | ```
|
58 |
|
59 | Use standardized exit codes if your adapter needs to terminate.
|
60 |
|
61 | ### `commonTools`
|
62 |
|
63 | A collection of various utility methods and modules from JS-Controller. Prefer this over trying to find `lib/tools.js` and similar internal modules from the controller yourself!
|
64 |
|
65 | Currently, the following **methods** are available:
|
66 |
|
67 | - `commonTools.pattern2RegEx` - Converts a pattern to match object IDs into a RegEx string that can be used in `new RegExp(...)`
|
68 |
|
69 | And the following **modules** are exposed:
|
70 |
|
71 | - `commonTools.password` - Previously exposed as `lib/password.js` in JS-Controller.
|
72 | - `commonTools.letsEncrypt` - Previously exposed as `lib/letsencrypt.js` in JS-Controller. Note that `letsEncrypt` has a capital `E`!
|
73 | - `commonTools.session` - Previously exposed as `lib/session.js` in JS-Controller.
|
74 | - `commonTools.zipFiles` - Previously exposed as `lib/zipFiles.js` in JS-Controller.
|
75 |
|
76 | ## Automatic backup of data files
|
77 |
|
78 | ioBroker has the ability to include files written by adapters in its backups. To enable that, you need to add the following to `io-package.json`:
|
79 |
|
80 | ```json
|
81 | {
|
82 | // ...
|
83 | "common": {
|
84 | // ...
|
85 | "dataFolder": "path/where/your/files/are"
|
86 | }
|
87 | }
|
88 | ```
|
89 |
|
90 | This path is relative to the path returned by `getAbsoluteDefaultDataDir()`. The placeholder `%INSTANCE%` is automatically replaced by the instance number of each adapter, for example `"dataFolder": "my-adapter.%INSTANCE%"`.
|
91 |
|
92 | ## Tips while working on this module
|
93 |
|
94 | - `npm run build` creates a clean rebuild of the module. This is done automatically before every build
|
95 | - `npm run lint` checks for linting errors
|
96 | - `npm run watch` creates an initial build and then incrementally compiles the changes while working.
|
97 |
|
98 | ## Errors in the definitions?
|
99 |
|
100 | If you find errors in the definitions, e.g. function calls that should be allowed but aren't, please open an issue here or over at https://github.com/DefinitelyTyped/DefinitelyTyped and make sure to mention @AlCalzone.
|
101 |
|
102 | ## Changelog
|
103 |
|
104 |
|
105 | Placeholder for the next version (at the beginning of the line):
|
106 | ### **WORK IN PROGRESS**
|
107 | -->
|
108 | ### 2.6.6 (2022-09-13)
|
109 |
|
110 | - (AlCalzone) Expose more JS-Controller internals under the `commonTools` export
|
111 |
|
112 | ### 2.6.2 (2022-09-07)
|
113 |
|
114 | - (AlCalzone) Fix: Restore compatibility with JS-Controller < 4.1
|
115 |
|
116 | ### 2.6.1 (2022-09-06)
|
117 |
|
118 | - (AlCalzone) Fix: detecting JS-Controller now finds the correct directory and not a subdirectory.
|
119 |
|
120 | ### 2.6.0 (2022-02-20)
|
121 |
|
122 | - (AlCalzone) Updated core declarations to `v4.0.1` for support with JS-Controller 4.x
|
123 |
|
124 | ### 2.5.1 (2021-07-22)
|
125 |
|
126 | - (AlCalzone) Updated core declarations to `v3.3.4`.
|
127 |
|
128 | ### 2.5.0 (2021-05-19)
|
129 |
|
130 | - (AlCalzone) Add fallback solution to detect js-controller if require.resolve fails in dev situations with symlinks
|
131 | - (AlCalzone) Use release-script for releases
|
132 | - (AlCalzone) Updated core declarations to `v3.3.0` to be up to date with JS-Controller 3.3.x.
|
133 |
|
134 | ### v2.4.0 (2020-05-03)
|
135 |
|
136 | - (AlCalzone) Updated core declarations to v3.0.6.
|
137 | - (AlCalzone) Expose the predefined collection of adapter exit codes as `utils.EXIT_CODES`
|
138 |
|
139 | ### v2.3.1 (2020-04-17)
|
140 |
|
141 | - (AlCalzone) Updated core declarations to v3.0.4.
|
142 |
|
143 | ### v2.3.0 (2020-04-15)
|
144 |
|
145 | - (AlCalzone) Updated core declarations to v3.0.2. This includes support for new methods in JS-Controller 3.0
|
146 |
|
147 | ### v2.2.1 (2020-01-27)
|
148 |
|
149 | - (AlCalzone) Included typings for the objects and states cache in the adapter class
|
150 |
|
151 | ### v2.0.0 (2019-12-27)
|
152 |
|
153 | - (AlCalzone) Updated core declarations to v2.0.0. This removes access to `adapter.objects` and `adapter.states`. You must use the new methods `adapter.getObjectView` and `adapter.getObjectList` instead of their counterparts from `objects`.
|
154 |
|
155 | ### v1.0.3 (2019-01-06)
|
156 |
|
157 | - (AlCalzone) Updated core declarations
|
158 | - (AlCalzone) Fix included declarations to allow creating adapter instances with `new`.
|
159 |
|
160 | ### v1.0.0 (2018-27-11)
|
161 |
|
162 | - (AlCalzone) Initial version
|
163 |
|
164 | ## MIT License
|
165 |
|
166 | Copyright (c) 2018-2022 AlCalzone
|
167 |
|
168 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
169 | of this software and associated documentation files (the "Software"), to deal
|
170 | in the Software without restriction, including without limitation the rights
|
171 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
172 | copies of the Software, and to permit persons to whom the Software is
|
173 | furnished to do so, subject to the following conditions:
|
174 |
|
175 | The above copyright notice and this permission notice shall be included in all
|
176 | copies or substantial portions of the Software.
|
177 |
|
178 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
179 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
180 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
181 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
182 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
183 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
184 | SOFTWARE.
|
185 |
|
\ | No newline at end of file |