Transceiver interface

This part of the documentation describes the use of the lower-level "transceiver" functions that enable transmitting and receiving 433MHz (or 868MHz) messages using a shell/executable interface. No nice screenshots, but explanation of the comand-line interface

The following topics are available:

• Compiling and building the code
• What interfaces are available
• Use LamPI-receiver as a daemon process
• Use LamPI-receiver as a sniffer or stand-alone
• Using the transmitter programs (for Kaku, Livolo, Action etc.)
• Message Formats (raw and jSon messages)

If you like to know more about the design/architecture considerations for this interface, please go to the architecture documentation.

Compiling and Building

The code is written in C, with source location in ~/receivers directory and with compiled code available in ~/exe subdirectory. You can compile and install the sources as follows:

> cd ~/receivers
> cd sniffer
> make

and to install use the following command:

> sudo make install

The compiled program will be put in the ~/exe directory and will have root privileges when running. The latter will allow regular users to execute the command while still being able to access the GPIO library and interfaces.

What interfaces are available?

This is different for the transmit or receiver function, and it also differs whether you just want to send messages using the commandline or whether you want some sort of daemon function that watches a well-known socket and based on incoming messages for a certain brand of equipment will use the correct transmitter command.

So let me explain.

• LamPI-receiver daemon; reads 433MHz handsets and transmits device commands over sockets on default port 5000 (socket TCP)
• Use LamPI-receiver as a stand-alone shell function to see incoming messages, timing and see statistics
• Use the shell transmitter executables to send single command to your connected devices

LamPI-receiver as daemon

The command to use to have LamPI-receiver behave as a daemon is:

> cd ~/exe ; ./LamPI-receiver -d &

which will start LamPI-receiver as a background process. If you like to start LamPI-receiver and get more information in log files:

> cd ~/exe; sh ./LamPI-receiver -d -s > ~/log/LamPI-receiver.log 2>&1 &

LamPI-receiver as a sniffer

LamPI-receiver actually should have been called LamPI-transceiver as the executable contains both transmitter and receiver functions. If you run LamPI-receiver as a command in a shell, it behaves as a receiver for incoming messages. Using the appropriate flags to the command it will behave as a sniffer for incoming wireless traffic and it will show brand, address, unit and status (On/OFF/dimlevel) information for every incoing 433MHz message that is recognized.

At the time of writing, the LamPI-receiver supports the following handsets, remotes and sensors:

• Klikaanklikuit.nl remote controls (kaku for short)
• Action (or impuls) handsets
• Livolo keychains
• Kopou keychains
• several other keychain FOB's or remotes that have similar message format as action
• Weather stations

The commandline sniffer can be activated as follows:

> cd ~/exe
> ./LamPI-receiver -v -s -t

The -v, -s and -t flags ar options and have the following meaning:

• -v; Verbose option, will output not only the resulting address, unit and value but also the bitstring
• -s; Statistics. This option will display statistics for every brand (it will keep administration for every supported receiver brand during the execution of the command) and it will display pulse-length/timing as well as shortest and longest pulse received for that type of device. This greatly helps debugging code.
• -t; Testing mode, will output pulse timing for every received message
• -d; Daemon mode. Officially the -d flag should not be used for command-line usage, but it allows debugging of the working daemon from the commandline with output as described while still working as a daemon and communicating with the LamPI-daemon process over socket connection.

Use transmitters on commandline (example)

There are several transmitter programs available for communication to 433MHz "connected" devices, supporting a range of (remote) 433MHz receiver devices from brands such as klikaanklikuit, Action, Blokker etc. Some I ported from Arduino example library in C++, some I wrote myself. Most common is of course the transmitter program for 433MHz klikaanklikuit receivers. The transmitter executable programs are located in the directory ~/exe. The source programs for these transmitters are located in the directory ~/receivers. This may feel strange (naming), but the directories are named ater the device types that are supported (receivers, for controlling remote receiver devices; sensors, for weather, temperature and humidity sensors; energy, for measuring power usage in the home) etc.

> cd ~/exe
> ./kaku -g 100 -n 1 on
> ./kaku -g 100 -n 2 8
> ./kaku -g 100 -n 2 off

Using the command ./kaku -h will provide help on the command interface. Most transmitters have following options:

• -g <switch address>; The group address is different for every brand of receiver. New kaku equipment has very large addresses that are coded in the remotes and switches can "learn" their address when pairing. Other brands such as Action/Impuls only have 31 room addresses and only 5(!) device addresses. This makes it VERY difficult to integrate action stuff easily in every room as you need to reserve one of the first addresses for sich switch.
• -n <device>; Like the address, the index number of devices is dependent on the brand implementation as well. For Action this is 1-5 (A-E) whereas for Kaku this can be 16 different devices in a group.
• -p <pin>; Optional flag for identifying the pin number of the Raspberry output pin.
• <value>; The last value in the chain does not have a leading flag. Its value is "on" or "off" for switches and van be a value for Kaku dimmers "0" to "31". For Livolo and Kopou wall switches, the on value will toggle the lights whereas the off value will switch off ALL devices with the same address (like pressing the D button on the remote will switch off the lights of A, B and C button.