Erlang

If needed, follow these Myriad guidelines for installing Erlang in order to obtain a proper, recent-enough version thereof.

Serial

We use our version [2] of erlang-serial for that, which we generally prefer, for standalone use, installing in user space (rather than in the system tree and embedded in a release) that way:

$ mkdir ~/Software && cd ~/Software
$ git clone https://github.com/Olivier-Boudeville/erlang-serial
$ cd erlang-serial
$ make && DESTDIR=. make install

Then using erlang-serial will be just a matter of adding it to one's code path [3].

To test this erlang-serial installation (whether or not any dongle is connected):

$ erl -pa $HOME/Software/erlang-serial/erlang/lib/serial-1.1/ebin
Erlang/OTP 25 [erts-13.0] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]

Eshell V13.0  (abort with ^G)
1> serial:start().
<0.82.0>

Perfect!

However we noticed repeatedly that after a few days the communication seemed to freeze bilaterally. Resetting serial once a day (e.g. at midnight) seemed to solve that problem.

However, after longer durations (e.g. 10 days), another issue happened: serial was still able to send telegrams, but not to receive any of them anymore - despite being restarted (indeed its PID was different each day as expected) and the TTY receiving the corresponding telegrams (as shown by od -x < /dev/ttyUSBEnOcean).

So we believe there is a defect in serial, but we could not figure out where. Ideas and contributions welcome!

Ceylan-Myriad

Oceanic expects to find a fully-built Myriad source tree as a sibling of its own tree, named myriad, and possibly made available through a symbolic link.

As per these Myriad guidelines, this source tree can be obtained by changing to a directory of choice that will contain both Myriad and Oceanic, and issuing:

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Myriad.git
$ ln -s Ceylan-Myriad myriad && cd myriad && make all && cd ..

Ceylan-Oceanic

From the same parent directory, very similarly:

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Oceanic.git
# Symlink just for consistency:
$ ln -s Ceylan-Oceanic oceanic && cd oceanic && make all && cd ..

Basic, Direct Command-line Testing

It is as simple as executing from the command-line (thus without Oceanic, Serial or even Erlang being involved):

$ od -x < /dev/ttyUSBEnOcean
0000000 0055 0707 7a01 10f6 2e00 96e1 0130 ffff
0000020 ffff 0039 554b 0700 0107 f67a 0000 e12e

(of course for such a binary content to be received, Enocean telegrams must be emitted; the simplest approach is to trigger any Enocean device able to send on demand such telegrams, like a button/rocker/switch)

hexdump can be also used to intercept telegrams. If needing to set the transmission speed beforehand, use stty -F /dev/ttyUSBEnOcean 57600.

Incoming data can also be recorded and "replayed" (yet this is not expected to activate an Enocean receiver, see Protocol Information):

$ cat < /dev/ttyUSBEnOcean > my_record.bin
$ cat my_record.bin > /dev/ttyUSBEnOcean

With a Graphical Serial Terminal

One may use cutecom to directly test input/output telegrams.

A priori neither RTS nor DTR shall be enabled (yet in our tests these had no impact with cutecom; however not disabling them with Oceanic was leading to emitting telegrams not understood by their target devices).

We recommend using the Hex input and output.

First test: executing a few Common Commands

This consists in having Oceanic discuss with the local USB gateway dongle, regardless of any actual Enocean device.

From the root of the Ceylan-Oceanic clone, supposing that Myriad and erlang-serial are already available and built (whereas here debug flags have been activated, see Oceanic's GNUmakevars.inc):

# Ensure erlang-serial is available:
$ make info-serial
ERLANG_SERIAL_BASE = /home/stallone/Software/erlang-serial/erlang/lib/serial-1.1

# Ensure that Ceylan-Oceanic is built:
$ make all

$ cd test

# Triggering a Common Command does not need any target device:
$ make oceanic_common_command_run

       Running unitary test oceanic_common_command_run (third form) from oceanic_common_command_test

--> Testing module oceanic_common_command_test.

Testing the management of Common Commands.
[debug] Using TTY '/dev/ttyUSBEnOcean' to connect to Enocean gateway, corresponding to serial server <0.86.0> (speed: 57600 bits per second).
[debug] Discovering our base EURID.
[debug] Sending to serial server <0.86.0> actual telegram <<85,0,1,0,5,112,8,56>> (hexadecimal form: '5500010005700838').
[debug] Waiting initial base request (ToSkipLen=0, AccChunk=<<>>).
[debug] Read telegram <<85,0,5,1,2,219,0,255,162,223,0,10,180>> of size 13 bytes (corresponding to hexadecimal '5500050102db00ffa3df000ab4').
[debug] Trying to decode '<<85,0,5,1,2,219,0,255,162,223,0,10,180>>' (of size 13 bytes)
[debug] Start byte found, retaining now following chunk (of size 12 bytes; after dropping 0 byte(s)):
 <<0,5,1,2,219,0,255,162,223,0,10,180>>.
[debug] Examining now following chunk of 12 bytes:<<0,5,1,2,219,0,255,162,223,0,10,180>>.
[debug] Packet type 2; expecting 5 bytes of data, then 1 of optional data; checking first header CRC.
[debug] Header CRC validated (219).
[debug] Detected packet type: response_type.
[debug] Full-data CRC validated (180).
[debug] Decoding a command response, whereas awaiting command of type co_rd_idbase, based on telegram <<85,0,1,0,5,112,8,56>> of size 8 bytes
(corresponding to hexadecimal '5500010005700838'), on behalf of requester internal.
[debug] Returning the following internal response: read gateway base ID ffa3df00, for 10 remaining write cycles.
[debug] Successfully read gateway base ID ffa3df00, for 10 remaining write cycles.
[info] No preferences file ('/home/stallone/.ceylan-settings.etf') found.
[debug] Waiting for any message including a telegram chunk, whereas having 0 bytes to skip, and having accumulated <<>>.
[debug] Requested to execute common command 'co_rd_version', on behalf of requester <0.9.0>.
[...]
[debug] Sending back to requester <0.9.0> the following response: read application
version 2.11.1.0, API version 2.6.3.0, chip ID 19d46ce, chip version 1162805507 and application description 'GATEWAYCTRL'.
[debug] Waiting for any message including a telegram chunk, whereas having 0 bytes to skip, and having accumulated <<>>.
Read version: read application version 2.11.1.0, API version 2.6.3.0, chip ID 19d46bc, chip version 1162805507 and application description 'GATEWAYCTRL'.
[debug] Requested to execute common command 'co_rd_sys_log', on behalf of requester <0.9.0>.
[...]
Read logs: read counters: 6 for application: [254,255,255,255,255,255], and 38 for API: [255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255].
[debug] Stopping the Oceanic server <0.85.0>.
[debug] Stopping serial server <0.86.0>, while in following state: Oceanic server using serial server <0.86.0>, using emitter EURID ffa3df00,
not having any command pending, based on a time-out of 1 second, with no command queued whereas a total of 2 of them have been issued;
having <0.9.0> registered as listener of Enocean events, having sent 3 telegrams, not having discarded any telegram, and knowing no Enocean device
[debug] Oceanic server <0.85.0> terminated.
Stopped.

--> Successful end of test.

(test finished, interpreter halted)

Second test: controlling an actual device

This more complete test will rely on experimental settings typically involving:

• a controller device (e.g. a double-rocker switch), which will be, once discovered, spoofed next by Oceanic
• a target device (e.g. a smart plug / socket switching actuator) that already learnt - according to its own procedure (typically pressing adequately buttons thereof) - the previous controller device; for example a lamp would be plugged on that actuator so that, when pressing and releasing a given button of the rocker switch, the lamp is toggled (on/off)

The objective is to control that lamp programmatically, through Oceanic (only).

First, the EURID of the controller device must be determined. Either it can be directly read from some actual label on the device, or it has to be obtained through passive listening.

In this last case, start by running the following test (still in oceanic/test):

$ make oceanic_integration_run

       Running unitary test oceanic_integration_run (third form) from oceanic_integration_test

--> Testing module oceanic_integration_test.

(test waiting indefinitely for Enocean events; hit CTRL-C to stop)
[debug] Using TTY '/dev/ttyUSBEnOcean' to connect to Enocean gateway, corresponding to serial server <0.86.0> (speed: 57600 bits per second).
[debug] Discovering our base EURID.
[...]
[debug] Waiting for any message including a telegram chunk, whereas having no byte to skip, and having accumulated no chunk.

Then act on the controller so that it emits a telegram (e.g. press a button of said rocker switch; it may be correspond for example to the bottom position of the first rocker, A).

If in range, the test should intercept it:

[debug] Received a telegram chunk of 21 bytes: <<85,0,7,7,1,122,246,48,0,46,225,150,48,1,255,255,255,255,68,0,254>>, corresponding to
hexadecimal 55000707017af630002ef1963001ffffffff4400fe (whereas there are 0 bytes to skip).[...]
[debug] Decoding an ERP1 radio packet of R-ORG f6, hence rorg_rps, i.e. 'RPS (Repeated Switch Communication)'...
[info] Discovering Enocean device 002ef196 through failure.

<----------------
[warning] Unable to decode a RPS (F6) packet for 002ef196: device not configured, no EEP known for it.
---------------->

[debug] Waiting for any message including a telegram chunk, whereas having no byte to skip, and having accumulated no chunk.
[...]

(hit CTRL-C to stop)

So we determined that this rocker switch has for EURID 002ef196.

We can notice that a failure is reported, as Oceanic cannot decode yet the telegrams from that emitter, short of knowing to which EEP it complies.

As this EEP information is not carried by such packets, it cannot be determined automatically and has thus to be specified, here once for all through a proper Oceanic configuration file, typically to be found as ~/.ceylan-settings.etf.

In this ETF file, among possibly other entries unrelated to Oceanic, we may have:

% Oceanic section:

% Information regarding the pseudo-device emitting any telegram to be sent by
% Oceanic:
%
% (if overriding the base ID of this chip, read as "ffa3df00")
%
%{ oceanic_emitter, "DEADBEEF" }.

% Attempting to spoof my green switch:
%{ oceanic_emitter, "002EF196" }.

% Threshold, expressed in bytes per second, regarding the incoming Enocean
% traffic (received telegrams), in order to trigger onEnoceanJamming events
% should that threshold be exceeded:
%
{ oceanic_jamming_threshold, 200 }.

% A list of device_config() entries, clearer with user-defined names than with
% only raw EURIDs:
%
{ oceanic_devices, [

   % Each device is to be described thanks to one of the three following
   % configuration terms:

   % { UserDefinedName :: ustring(), EURIDStr :: eurid_string(),
   %   EEPStr :: ustring() } % Then the activity periodicity will be learn

   % { UserDefinedName :: ustring(), EURIDStr :: eurid_string(),
   %   EEPStr :: ustring(), declared_device_activity_periodicity() }

   % { UserDefinedName :: ustring(), EURIDStr :: eurid_string(),
   %  EEPStr :: ustring(), ActPeriod :: declared_device_activity_periodicity(),
   %  Comment :: ustring() }.


   % For the local gateway (useful to decode/check self-encoded telegrams):
   { "my local USB gateway", "ffa3df00", "F6-02-01" },

   % Single-input contacts:
   { "my first opening sensor", "060533EC", "D5-00-01", learn, "Battery to be added (too dark)" },
   { "my second opening sensor", "02959F62", "D5-00-01" },

   % Temperature and humidity sensors:
   { "my only temperature and humidity sensor", "02A96926", "A5-04-01" },

   % Switches:
   { "my green switch", "002EF196", "F6-02-01",
     "This is actually a single-rocker switch" },
   { "my white switch", "012F50D6", "F6-02-01" },

   % In-wall modules:

   % Expected period of about 25 minutes:
   { "my two-channel orange module", "06035E4A", "D2-01-12", { 0, 0, 25, 0 } },

   % Socket switching actuators:
   %{ "my smart plug", (unknown), (unknown) }

   ] }.

These entries are pretty self-explanatory and have already been described in Configuring Oceanic:

• with oceanic_emitter we define the EURID that shall be used by Oceanic whenever emitting (the default being its in-chip first base ID, as automatically determined thanks to a Common Command)
• with oceanic_jamming_threshold we can define our own level of incoming traffic above which Oceanic shall consider that an attempt of jamming is taking place
• with oceanic_devices the EEP of the various devices that we want to be aware of are listed (naming them allows to have clearer Oceanic reports)

Now, as the test explicitly sets the EURID of the emitter, it is just a matter of updating, in oceanic_static_sending_test.erl, the SourceEurid variable in order that this test impersonates the controller of interest (here, said green switch):

SourceEurid = oceanic:string_to_eurid( "002EF196" ),

Running it [4] results in:

$ make oceanic_static_sending_run
       Running unitary test oceanic_static_sending_run (third form) from oceanic_static_sending_test

--> Testing module oceanic_static_sending_test.

Starting test; note that direct telegram sendings are made here, thus Oceanic will detect responses that do not match with any past request that it sent.
[debug] Using TTY '/dev/ttyUSBEnOcean' to connect to Enocean gateway, corresponding to serial server <0.86.0> (speed: 57600 bits per second).
[debug] Discovering our base EURID.

[debug] Successfully read gateway base ID ffa3df00, for 10 remaining write cycles.
[debug] Initial state: Oceanic server using serial server <0.86.0>, using emitter EURID ffa3df00, not having any command pending, based
on a time-out of 1 second, with no command queued whereas none has been issued; not having a listener of Enocean events registered,
having sent a single telegram, not having discarded any telegram, and knowing 8 Enocean devices:
+ device 'my first opening sensor' (EURID: 060533ec) applying EEP D5-00-01; it has been never seen by this server
[...]
Decoding the 'pressed' one for the 'off' button results in following event: double-rocker device 'my green switch' (whose EURID is 002ef196) has no button
pressed simultaneously at 2022/11/19 23:11:45, declared with a single subtelegram, targeted to the address for broadcast transmission; security
level: telegram not processed; its EEP is double_rocker_switch (F6-02-01)
[...]
All telegrams of interest encoded.
First we press (and then also release) the 'switch off' button, 'button_ao' (which must have already been learnt), typically in order to switch on a lamp.
Then, after a short waiting, we press (and then release) this 'switch off' button again, 'button_ai', typically to switch off the lamp.
[debug] Sending to serial server <0.86.0> actual telegram <<85,0,7,7,1,122,246,16,1,9,217,112,32,1,255,255,255,255,255,0,204>>
(hexadecimal form: '55000707017af6100109d9702001ffffffffff00cc').

The lamp is expected first to turn on, then, and after one second, to turn off.

Congratulations, your Oceanic program can control electrical appliances!

If this test does not work as intended:

• did the right position of the right button was learnt?
• depending on the switch, apparently:
  • either each of the individual buttons will act as a rocker by itself (e.g. to switch on then off the lamp, a learnt button - top or bottom - of a given rocker will have to be pressed and released twice [5])
  • or the whole rocker (that is the pair made of its top and bottom buttons) will work as intended as a rocker (e.g. to switch on the lamp, the top button will have to be pressed and released, then, to switch off the lamp, the bottom button will have to be pressed and released [6])

Guarding Against Spoofing: Lying about One's Source EURID Will Not Suffice

Provided that the serial link is properly configured (in terms of speed, parity, start/stop bits, RTS/CTS flow control, etc.), apparently even with the default, usual level of security (that is: none) implemented by the devices that we tested, Enocean telegrams could not be replayed [7]: just intercepting a raw telegram and re-emitting was not acknowledged by the target device and did not trigger its intended effect on at least our main test actuator (e.g. the smart plug did not switch on/off).

One explanation could have been that we were re-emitting from Oceanic "receive" telegrams (as opposed to "send" ones), as we actually always receive information different from what was sent (e.g. the dbM measure, the repeating count, etc. are visibly set between the emission and the receiving; and of course the checksums are modified accordingly) - so replaying a received telegram could be rejected on these bases.

Nevertheless, forging from scratch proper "send telegrams" (yet carrying the same functional information) and sending them by ourselves still did not trigger the actuator (we did multiple tests on multiple devices of different manufacturers).

So we believe that extra information is available to actuators through the Enocean network stack, that may/will be used by them in order to discriminate between actual emitters.

This was further confirmed by testing the same telegram exchanges after having learnt a device, either the real one, or one impersonated by Oceanic: apparently, only the ones that have been explicitly learnt previously will be accepted afterwards.

By forging telegrams bearing a source EURID different from the base one, we came to the conclusion that:

• most if not all telegrams carry a source EURID that can be freely set (typically through Oceanic calls)
• yet in parallel each emitter (be them an USB dongle controlled by Oceanic or a "real" device) has its own internal, "base" ID (or a base ID range, for such dongles); these IDs have the same type as EURIDs, and we suppose that they can be considered as actual EURIDs - yet they could be handled specifically only in low-level ESP3-like protocols (invisibly from the "applicative layer" seen when exchanging with the dongle); by default, unless specified (see the oceanic_emitter configuration entry), the source EURID used by telegrams generated by Oceanic match the ID obtained (through a Common Command) from the USB dongle [8]
• learning a device relies at least on these internal IDs, sometimes also on the specified in-telegram source one
• a telegram will be considered by an actuator iff the internal ID of the emitter carried by this telegram matches with one that has been learnt by the actuator (hence no easy spoofing with rogue, undeclared emitters)
• the source EURID included in a telegram will designate a device but may not match the internal ID of the emitter; so for example we could forge, from Oceanic, telegrams whose source EURID matches the one of an actual device (a rocker switch) - and therefore did not match the internal ID of the dongle - while nevertheless, provided that the dongle had already been learnt by the actuator, typically thanks to a previous Oceanic sending, we could operate the actuator programmatically (despite these telegrams having inconsistent IDs)
• yet, do these Oceanic telegrams have to specify the same EURID as used for their registering, or any already-registered EURID - or would any EURID would do the trick?

• for the repeating mechanisms to have an interest, their re-emitted telegrams must be taken into account by the target actuators; so accepting already-sent telegrams emanating from different emitters than the one specified in the telegrams is needed; repeating is most probably handled transparently by lower-level protocols as well

  [8]

  This is merely a convention though, as apparently any another EURID could be used instead at this level. We used to add "provided it is consistently used from then on" (that is: when learning and also when sending telegram afterwards), yet we could see that even forging a telegram with a random source EURID but sending it from a right, already learnt device (hence using another EURID then) is sufficient to have the corresponding request accepted and processed - at least by some actuators.

We can also verify that devices like rocker switches are apparently stateless, in the sense that they seem to send the same information regardless of their history when one of their buttons is pressed (they have no memory).

So from our experiments we believe that, in terms of identification, the devices rely on a lower-level protocol (possibly ESP3) than the one that can be handled programmatically (e.g. ERP1 and siblings); as these operations seem to be done through the firmware of the USB gateway, spoofing Enocean traffic may be out of the reach of programs relying on "standard" USB gateways (therefore Oceanic having to be involved also in the learn process, not only in the emitting one).

And forging custom source EURIDs may have an interest, yet the spoofer must have been previously learnt - otherwise this would be a bit like if one was spoofing IP addresses in forged packets, whereas the target device would first compare MAC addresses.

Other Network-Related Risks

The spoofing risk being mostly alleviated, the only extra risks that we could foresee are:

• possibly brute-force attempts to match already-learnt base identifiers, from a debug gateway allowing to act on ESP3 packets (a threat that does not seem likely for common burglaries)
• the jamming of an actuator by saturating it with telegrams (be them well-formed and sensible, or not [9]), so that any actual telegram of interest (e.g. regarding a door opening) may not reach the receiver
• sensors devices being incapacitated before they are able to raise an alarm (for example destroyed, or possibly flashed by an electromagnetic impulse)

Oceanic provides basic yet possibly sufficient mechanisms guarding against these three threats.

For the first two risks: in a wireless context, nothing can be done against emission, but a configurable threshold in terms of incoming traffic volume can be monitored (with proper back-off), so that, if the application registered as a listener, Oceanic notifies it whenever detecting such an attempt of denial of service - which can be considered by itself as a cause of alarm as serious as the other ones.

This threshold is expressed in bytes per second (knowing that telegrams are often fragmented), and its default value (see the oceanic_jamming_threshold configuration entry) is 250. As the size of many Enocean legit telegrams is 21 bytes, an onEnoceanJamming event will be sent to the Oceanic-using application should a dozen of them be received during the same second, or a bit more in (a bit) longer time window (e.g. 20 in two seconds).

For the last risk, sensors (typically opening detectors) report instantly state transitions but also send periodic state notifications (even if no change happened). So a listener can monitor the duration elapsed since such a sensor was last seen, and if it exceeds a threshold (for example 30 minutes [10]), this may considered as a reason to raise an alarm.

For that, the user may request the activity periodicity of a device to be monitored.

The corresponding checking period (refer to the declared_device_activity_periodicity/0 type) can be:

• directly specified by the user, as a DHMS duration; for instance {0,0,12,0} will denote an expected (maximum) duration of up to 12 minutes (0 Day, 0 Hour, 12 Minutes, 0 Second) between two telegrams sent by this device - otherwise the sensor will be reported as lost
• a default one (see default_dhms_periodicity), if the configuration specified default
• determined automatically by Oceanic, based on the rhythm that it could learn from past traffic emanating from this device, if the configuration specified learn or did not set it

Whenever the checking period of a sensor elapses whereas no telegram from it has been received during that time frame, any process registered as an Oceanic event listener will be sent an onEnoceanDeviceLost message, specifying notably the name and EURID of that device, when it has been seen last, and what its expected periodicity was.

Studying Actual Protocols

To experiment and troubleshoot communication issues (this may be especially of use should different devices/actuators interpret differently the Enocean specifications / develop their own behaviour), one may also use tests that perform direct listening / emitting (possibly bypassing partly the logic of the Oceanic server):

• use make oceanic_just_record_device_run to display and record in file (enocean-test-recording.etf) all raw, timestamped telegrams that can be intercepted
• use make oceanic_just_send_to_device_run to emit raw telegrams, typically recorded as explained above or forged (encoded) by Oceanic

Corresponding very handy scripts are available as well, decode-telegram.sh and send-telegram.sh, to which a raw telegram can be given (as an hexadecimal string).

Usage Hints