EnOcean-Core is a TypeScript implementation of (some of) the core functionality of the EnOcean protocol for Node.js. This library can be used with a TCM310 transceiver module to implement a basic EnOcean gateway. Currently the implemented features are:
This library provides a high-level interface (API) to communicate with EnOcean devices in Node.js. The EnOcean functionality is encapsulated in such a way that it is easy to use, without having to dig into all the technical details of the underlying EnOcean Serial Protocol. Nevertheless, a basic understanding of EnOcean concepts like
is required to use this library.
The library is developed as part of the author's efforts to build a modern, open source home automation system (not yet released publicly). Hence the library's architecture is (of course) built with this application in mind.
While most of this library's data structures are hardware-independent, actual communication with physical EnOcean devices has only been tested with a TCM310 transceiver module. To the author's knowledge, this module is currently commercially available in two formats, namely
This library has been tested with both variants.
As the name of this library suggests, it only implements core functionality of the EnOcean protocol. In order to actually communicate with devices, it is necessary to separately implement the corresponding EnOcean Equipment Profile (EEP).
Currently, parsers for the following EEPs are available (as separate libraries, to be published soon). It is also possible to implement own parsers.
Internally, communication with the TCM310 and with other EnOcean devices uses the EnOcean Serial Protocol 3 (ESP3). Note that
If you are missing a feature, feel free to submit a feature request. Alternatively, you can also contribute.
If you search for the term "enocean" on npmjs.com, you will find many packages implementing the EnOcean protocol for Node.js. However, when the author of this library started working on implementing EnOcean functionality in his home automation software in 2020, he identified two major drawbacks:
While this may have changed by now (and might of course also have been just a personal impression at that time), the author decided that the best solution for his problem (i.e. his own home automation software) was to implement this library from scratch using the official EnOcean documentation.
This library is available as a Node.js-module. You can thus use Node.js' package manager npm to install the latest production version from the npm registry by executing
npm i enocean-core
in your Node.js project's repository. This will automatically also install the following dependencies.
| Name | Description | License |
|---|---|---|
| Node SerialPort | Node.js package to access serial ports for Linux, OSX and Windows. | MIT |
| Node SerialPort's InterByteTimeoutParser | Parser for Node SerialPort; emits data if there is a pause between packets | MIT |
| Byte | A class for simple bit manipulation. | Apache-2.0 |
Since this framework is written in TypeScript, you can use it both with TypeScript as well as with plain JavaScript. Below you can find short examples to get you started in both languages.
The library also comes with an online documentation. A good starting point for further reading is the documentation of the Gateway class. Moreover, as this documentation is generated from source code comments using TypeDoc, a supported editor (like Visual Studio Code) can provide on-the-fly information on functions, parameters, etc..
To use any of the functionality we need to import the module. Moreover, for actual sending/receiving, we need to create a gateway and connect it to a serial port (with a supported transceiver attached, see above for the supported hardware).
import * as EnOcean from "enocean-core"
const gateway = EnOcean.Gateway.connectToSerialPort('COM3')
Make sure to replace COM3 with a valid address/path for your hardware. Note that COM3 is a Windows address, on Linux with a EnOcean Pi hat, the address could be e.g. /dev/ttyAMA0.
Once we have imported the module and instantiated a gateway, we can use it to listen for all incoming ERP1 telegrams.
gateway.onReceivedERP1Telegram((telegram) => {
console.log(telegram.toString())
})
The gateway will automatically interpret any received data as far as possible. Due to the EnOcean protocol, a necessary prerequisite for this is that the gateway knows the EEP of the sending device. There are two possible options to achieve this.
To listen and interpret messages, it is sufficient to simply tell the gateway the EEP of a device. Suppose we have a simple rocker switch with ID '12:34:56:78' sending data according to EEP 'F6-D2-01' then we can manually teach the gateway using the following code.
gateway.teachDevice(
DeviceId.fromString('12:34:56:78'),
EEPId.fromString('F6-D2-01'),
)
Now, each button push on the button will be automatically interpreted as described below.
While for simple EnOcean sensors (like the above rocker switch) only the gateway needs to know the sensor, more sophisticated devices (in particular actuators) require a mutual teach-in. The usual procedure consists of two steps:
Set the gateway in learning mode. This can be done with the following code.
gateway.startLearning(120)
Here, the learning mode will be active for 120 seconds.
Trigger the teach-in/learning process on the actuator.
If the gateway is able to successfully learn the new device, it will emit an event. Thus to get notified of a successful teach-in, we can register a listener as follows.
gateway.onDeviceTeachIn((device, info) => {
console.log('Teach-in sucessfully completed for device ' + device.toString())
})
The listener will also be called on manual teach-ins (see above). Currently the gateway only supports the following teach-in procedures:
After a successful teach-in (either manually or automatically), the gateway will try to automatically interpret all incoming messages from these known devices. We can listen to all successfully interpreted message as follows.
gateway.onReceivedEEPMessage((message, telegram) => {
console.log(message)
})
Note in the example that the listener can also access the telegram in which the message was enclosed. Besides knowing the device and its EEP, a necessity for successful interpretation is the existence of a so called 'EEP parser' for the respective EEP. See above for a list of supported EEPs, i.e. for EEPs for which a parser is available.
Sending raw ERP1 telegrams is simple.
const result = await this.sendERP1Telegram(telegram)
If the returned value is 0, sending succeed. Otherwise the returned number will give the reason why sending failed.
Contact the main author (Henning Kerstan) if you want to contribute. More details will be available here soon.
This project uses semantic versioning. However, despite most of the API being ready, note that since we are still in development (version 0.x.y), anything may yet change at any time.
For detailed information on the (minimal) required versions, have a look at the package.json.
As this library has not yet fully matured (version is still < 1.0.0), please have a look at the git commit log for a version history.
Copyright 2021 Henning Kerstan
SPDX-License-Identifier: Apache-2.0
EnOcean® and the EnOcean logo are registered trademarks of EnOcean GmbH. All other product or service names are the property of their respective owners.
Generated using TypeDoc