HiPi
Perl Modules for Raspberry Pi
Version 0.68 - released 29 November 2017

hipi_energenie

The hipi-energenie command allows you to control and monitor the Energenie range of sockets, switches and sensors directly from the command line using either the Energenie ENER314_RT 2 way transceiver board or the Energenie ENER314 1 way transmitter board.

The ENER314 1 way transmitter board can only switch on and off up to 4 control only sockets or switches.
The ENER314_RT 2 way transceiver board can switch any number of control only sockets or switches and can control and monitor smart adapters and sensors.
Command Line Help
Help for individual commands
Configuring the Command
Setting the board type
Changing the SPI device
Controlling Switches and Sockets
Creating a Group
Pairing a Socket
Switching a Socket
Monitors and Smart Adapters
Pairing with a Monitor, Sensor or Adapter
Querying a Monitor
Switching an Adapter
Scripting hipi-energenie commands
Returning command output as JSON
Using the HiPi::Energenie::Command module

Command line Help

hipi-energenie provides help for all commands. At the top level, the command:

hipi-energenie help

provides initial help on command usage

pi@raspberry:~ $ hipi-energenie help

  usage : hipi-energenie <command> [options]

  command :
    help        Print this message
    version     Print the version
    config      Configure the board type ( ENER314_RT or ENER314 )
    group       Manage groups for use with sockets
    pair        Pair a socket or switch
    alias       Rename or name a socket or switch
    switch      Switch a socket or switch on or off
    join        Configure a monitor or adaptor
    adapter     Switch an adapter device on or off
    monitor     Query a monitoring device for values

  For help on each command use:
    hipi-energenie <command> -h

Help for individual commands

Each command has its own help. To view this pass the command option --help or -h

For example, for help on the join command

hipi-energenie join --help

Help is output to the console.

pi@raspberry:~ $ hipi-energenie join --help

  usage : hipi-energenie join < options >

  description: Join a Mi|Home monitor or adapter. Run this command first and
               then switch your adapter or monitor to join mode.

  options :

    --help        -h  Display this message

    --list        -l  List the adapters and monitors already joined

    --name        -n  < name > A name for the adapter or monitor. This
                      is required.

    --rename      -r  < name > You can rename an adapter. If --rename is specified
                      then --rename contains the existing name and --name contains the
                      new name.

    --delete      -d  < name > Remove the named monitor or adapter from configuration

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

Configuring The Command

Before using hipi-energenie there is some basic configuration you must create. This is achieved using the command

hipi-energenie config

Calling the command with no options lists the current configuration. The first time hipi-energenie is run it will create a default configuration.

pi@raspberry:~ $ hipi-energenie config

CONFIGURATION
-----------------------------------------
  Config Version   :  0.61
  Energenie Board  :  ENER314_RT
  Receiver         :  YES
  Uses SPI         :  YES
  SPI Device       :  /dev/spidev0.1
  Config Saved     :  2017-09-18 02:55:46

You can change the type of board you have connected to the Raspberry Pi( ENER314_RT or ENER314 )

If you are using the ENER314_RT you can change the /dev device it is connected to ( /dev/spidev0.1, /dev/spidev0.0, etc. )

To get help on using the config command, use option --help or -h

hipi-energenie config -h
pi@raspberry:~ $ hipi-energenie config -h

  usage : hipi-energenie config <options>

  options :

    --help        -h  Display this message

    --list        -l  List the current config

    --board       -b  < ENER314 | ENER314_RT > Set the board type that
                      you have connected to the Raspberry Pi.
                      Default is 'ENER314_RT'

    --device      -d  < devicename > Set the SPI device used by the
                      ENER314_RT board. Default is '/dev/spidev0.1'

    --reset       -r  < gpio > Specify the GPIO pin connected to
                      the reset pin on the ENER314_RT board.
                      Default is 25 ( RPI_PIN_22 )

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

After each config command the resulting configuration is output to the console.

Note that your configuration and all settings for switches and adapters are saved in a user specific configuration file.

For example, for user pi it is stored at

/home/pi/.hipi-perl/scripts/energenie/user.conf

For user root the configuration is stored at

/etc/hipi-perl/scripts/energenie/global.conf

This means that if you wish to run scripts that call hipi-energenie commands from the global cron, you need to either create your configuration using sudo hipi-energenie, copy your user.conf to the global.conf, or probably best, su to user pi in your cron.

You should backup your config file after making changes as it contains all the ids for your configured devices.

Setting the board type

hipi-energenie can currently use two types of RF boards

The ENER314_RT board is a 2-way transceiver that allows you to manage sensors and monitors in addition to switches and sockets.

The ENER314 board can control just 4 individual sockets or one 4 gang extension.

The board can be set using the --board option to the config command

hipi-energenie config -b ENER314_RT
hipi-energenie config -b ENER314

Changing the SPI device

If you are using the ENER314_RT board you can set which SPI device it is connected to. By default if the ENER314_RT is connected directly to the Raspberry Pi header, it will use device /dev/spidev0.1 but you may have connected to a difference SPI using your own setup rather than fitting the board directly to the GPIO header.

To change the SPI device, use the --device option to the config command.

hipi-energenie config -d /dev/spidev0.1
hipi-energenie config -d /dev/spidev0.0

Controlling Switches and Sockets

Basic switches and sockets from Energenie can be controlled in groups of 4. This is because the protocol used to switch on and off uses a unique group id plus the socket number - 1 to 4.

If you are using the 1 way transmitter board ENER314 then the maximum number of sockets you can control individually is 4. This is because the group id is hard coded into the board in the same way that one of the Energenie hand held remotes works. It is suggested that you can control more than 4 switches which is technically true but only if you pair more than one switch with a switch number and switch all of those devices on or off at the same time.

If you are using the ENER314_RT 2 way transceiver you can set the group id to use when sending a command in software so the number of switches you can control is not limited by having a single fixed group id.

Creating a Group

To start controlling sockets we must first create a group. We do this using the group command.

hipi-energenie group --help
pi@raspberry:~ $ hipi-energenie group -h

  usage : hipi-energenie group < options >

  description: Set up groups for use with ENER314_RT board to control
               multiple sets of simple switches or sockets.

  options :

    --help        -h  Display this message

    --list        -l  List the currently configured groups

    --create      -c  < name > Create a new group. The system will create a new
                      unused group id and associate the supplied name with it.
                      e.g. hipi-energenie group -c newname
                      Provide option --groupid to name an existing group.

    --delete      -d  < name > Delete an existing group.
                      e.g. hipi-energenie group -d 'my group 1'

    --rename      -r  < name > Rename an existing group. Must be accompanied
                      by option for --newname.
                      e.g. hipi-energenie group -r oldname -n newname

    --newname     -n  < name > The new name for a group. (used with --rename)

    --groupid         < groupid > The group id identifier that is used
                      to control a group of four switches or sockets,
                      or one 4 way gang extension. This is a number
                      between 0x01 and 0xFFFFF. The parameter can be
                      passed in decimal, hexadecimal or binary
                      notation. It is parsed by the Perl 'oct'
                      function.

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

We can create a group called 'mysockets' using the command

hipi-energenie group -c mysockets

After this command all the groups we have created are listed

pi@raspberry:~ $ hipi-energenie group -c mysockets

GROUPS
-----------------------------------------
  mysockets                      0x08EEB4

We can use the group command to create more groups, rename groups, delete groups and list the groups we have created.

Pairing a Socket

To control a switch or socket it must first be paired with a group id and switch number.

This is achieved by putting the socket into paring mode and sending a command from your controller. Generally the device can be put into pairing mode my keeping its button depressed for a few seconds until the light on the device begins to flash.

We can pair a socket using the pair command.

pi@raspberry:~ $ hipi-energenie pair -h

  usage : hipi-energenie pair < options >

  description: pair with a simple socket or switch such as an ENER002 switch
               socket; an ENER010 4 way extension; a Mi|Home MIHO002 adapter.
               Set the adapter to pairing mode and run this command.

  options :

    --help        -h  Display this message

    --list        -l  list paired switches

    --groupname   -g  < groupname > A groupname you have configured using the
                      group command. If you are using the transmit
                      only ENER314 board, this option is ignored.

    --switch      -s  < 1 | 2 | 3 | 4 > The number of the switch or socket
                      you want to pair. Each groupname can control a
                      maximum of 4 switches. If you are pairing an
                      ENER010 4 gang extension, use '1'

    --name        -n  < switchname > A name for the paired switch
                      that you may use in the future to command the switch
                      rather than specifying both group and switch
                      number.

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

    ( to rename a switch / group pair use the 'alias' command )

To pair a socket as socket 1 of group 'mysockets' and give it a name 'Wall Plug":

Put the socket into pairing mode and issue the following command:

hipi-energenie pair -g mysockets -s 1 -n "Wall Plug"

Control only sockets and switches do not transmit any information so the only indication that pairing has been successful comes from the device itself - normally by stopping flashing its light.

When the command has completed a list of your currently paired switches is displayed

pi@raspberry: $ hipi-energenie pair -g mysockets -s 1 -n "Wall Plug"

SWITCHES & SOCKETS
------------------------------------------
  NAME               GROUP          SWITCH
  Wall Plug          mysockets           1

You can now switch the socket on and off using the switch command.

Switching a Socket

You can switch a previously paired socket or switch on or off using the switch command

pi@raspberry:~ $ hipi-energenie switch -h

  usage : hipi-energenie switch < options >

  description: Turn a paired socket or switch on or off

  options :
    --help        -h  Display this message

    --list        -l  List the currently configured switches

    --name        -n  < switchname > An alias for the groupname / switch pair

    --groupname   -g  < groupname > If you don't provide a name you can specify
                      groupname and switch number instead. This is the
                      groupname you paired the switch with.
                      If you are using the transmit only ENER314 board,
                      this option is ignored.

    --switch      -s  < 0 | 1 | 2 | 3 | 4 > If you don't provide a name you can
                      specify groupname and switch number instead. This is the
                      number of the switch or socket you want to switch.
                      Specifying 0 switches all members of the group.

    --on          -1  Switch the socket on

    --off         -0  Switch the socket off

    --all             Switch all sockets in the group. The same as specifying
                      --switch 0

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

To switch a device we previously paired as "Wall Plug"

hipi-energenie switch -n "Wall Plug" --on
pi@raspberry: ~ $ hipi-energenie switch -n "Wall Plug" --on

SWITCH BROADCAST STATUS - ON
-------------------------------
  GROUP                  SWITCH
  mysockets                 1
hipi-energenie switch -n "Wall Plug" --off
pi@raspberry: ~ $ hipi-energenie switch -n "Wall Plug" --off

SWITCH BROADCAST STATUS - OFF
-------------------------------
  GROUP                  SWITCH
  mysockets                 1

Monitors and Smart Adapters

Montitors and smart adapters such as the MIHO004 Mi|Home Smart Monitor plug and the MIHO005 Mi|Home Smart Adapter Plus can both broadcast and receive information

Pairing with a Monitor, Sensor or Adapter

To control a smart product you must 'join' with the product first using the join command.

hipi-energenie join --help

Help is output to the console.

pi@raspberry:~ $ hipi-energenie join --help

  usage : hipi-energenie join < options >

  description: Join a Mi|Home monitor or adapter. Run this command first and
               then switch your adapter or monitor to join mode.

  options :

    --help        -h  Display this message

    --list        -l  List the adapters and monitors already joined

    --name        -n  < name > A name for the adapter or monitor. This
                      is required.

    --rename      -r  < name > You can rename an adapter. If --rename is specified
                      then --rename contains the existing name and --name contains the
                      new name.

    --delete      -d  < name > Remove the named monitor or adapter from configuration

    --json            The command results will be output as a JSON
                      string. This can be used when you want to parse
                      the command output from external code.

    --pretty          The command results will be output as formatted JSON
                      with line breaks and indentation.

To join with a device and call it "New Adapter", run the command:

pi@raspberry:~ $ hipi-energenie join -n "New Adapter"

The command will wait for a join message from the device. To send this, switch the device off and depress its button until the light begins to flash. You should see the following output.

pi@raspberry:~ $ hipi-energenie join -n "New Adapter"

Listening for join messages from adapters and monitors. Set your device mode to join ....


MONITORS AND ADAPTERS
---------------------------------------------------------------------
  NAME                 PRODUCT                      SENSORID   SWITCH
  New Adapter          Mi|Home Adapter Plus         0x002BA0      YES

Querying a Monitor

You can now control the adapter by name. To query it for information:

pi@raspberry:~ $ hipi-energenie monitor -n "New Adapter"

MONITOR STATUS REPORT FOR "New Adapter"
---------------------------------------------
  Sensor Type           Mi|Home Adapter Plus
  Sensor Key            0004-0002-002FC8
  Timestamp             2017-09-21 12:43:45
  -------------------------------------------
  Real Power            0 W
  Reactive Power        0 VAR
  Voltage               248 V
  Frequency             49.94921875 Hz
  Switch State          OFF

Switching an Adapter

To switch the adapter on :

pi@raspberry:~ $ perl hipi-energenie adapter -n "New Adapter" --on

ADAPTER STATUS REPORT FOR "New Adapter"
---------------------------------------------
  Sensor Type           Mi|Home Adapter Plus
  Sensor Key            0004-0002-002FC8
  Timestamp             2017-09-21 12:46:17
  -------------------------------------------
  Switch State          ON

To switch the adapter off :

pi@raspberry:~ $ perl hipi-energenie adapter -n "New Adapter" --off

ADAPTER STATUS REPORT FOR "New Adapter"
---------------------------------------------
  Sensor Type           Mi|Home Adapter Plus
  Sensor Key            0004-0002-002FC8
  Timestamp             2017-09-21 12:48:04
  -------------------------------------------
  Switch State          OFF
           

Scripting hipi-energenie commands

The hipi-energenie command can also easily be called from other scripts or your own Perl code and the return results parsed.

Returning command output as JSON

Adding the option --json to any command will return the command result as a JSON string.

During development of your calling script, you can use the option --pretty instead to return an indented JSON string with line breaks.

pi@raspberry:~ $ hipi-energenie monitor -n "New Adapter" --pretty
{
   "command" : "monitor",
   "data" : {
      "configured_name" : "New Adapter",
      "manufacturer_id" : 4,
      "manufacturer_name" : "Energenie",
      "product_id" : 2,
      "product_name" : "Mi|Home Adapter Plus",
      "records" : [
         {
            "command" : 0,
            "id" : 112,
            "name" : "Real Power",
            "units" : "W",
            "value" : 0,
            "value_type" : 128
         },
         {
            "command" : 0,
            "id" : 113,
            "name" : "Reactive Power",
            "units" : "VAR",
            "value" : 0,
            "value_type" : 128
         },
         {
            "command" : 0,
            "id" : 118,
            "name" : "Voltage",
            "units" : "V",
            "value" : 248,
            "value_type" : 0
         },
         {
            "command" : 0,
            "id" : 102,
            "name" : "Frequency",
            "units" : "Hz",
            "value" : 49.94921875,
            "value_type" : 32
         },
         {
            "command" : 0,
            "id" : 115,
            "name" : "Switch State",
            "units" : "",
            "value" : "0",
            "value_type" : 0
         }
      ],
      "sensor_id" : 12232,
      "sensor_key" : "0004-0002-002FC8",
      "switch_state" : "0",
      "timestamp" : "2017-09-21 13:24:10"
   },
   "error" : "",
   "errorcode" : "ERROR_SUCCESS",
   "option" : "query",
   "success" : 1
}

You check the return value of 'success'. If it is true, the returned information will be in the "data" member.

If there was an error, "success" will be false, a string constant will be in "errorcode" and an error decription in "error".

pi@raspberry:~ $ hipi-energenie monitor -n "Bad Name" --pretty
{
   "command" : "monitor",
   "data" : {},
   "error" : "Could not find a configured monitor named Bad Name",
   "errorcode" : "ERROR_MONITOR_NAME_NOT_FOUND",
   "option" : "",
   "success" : 0
}

Using the HiPi::Energenie::Command module

The hipi-energenie command uses the module HiPi::Energenie::Command internally. You can call the same method directly in your own code.

Pass the elements of any hipi-energenie command as an array to the method "handle_command_arguments".

# to replicate a command line call to
# hipi-energenie adapter -n "New Adapter" --off

use HiPi::Energenie::Command;
use JSON;

my $handler = HiPi::Energenie::Command->new;

my $json = $handler->handle_command_arguments( 'adapter', '-n', 'New Adapter', '--off', '--json' );
my $ref = decode_json( $json );

if($ref->{success}) {
    .... good
} else {
    .... bad
}