Enistic Controller API
The Enistic Controller API is a simple low level way of accessing meter readings and controlling our Smart Sockets. The protocol is based on the UDP protocol and uses broadcast messages to communicate to/from the controller. This API can be used with our Smart Energy Controller or our Smart Energy Controller Lite.
Development environment
Any programming language that allows you access to your network should be appropriate to develop a system that interfaces to our controllers. We have working systems using PHP and .NET but many others are possible as most languages support this type of programming. As the system is based purely on TCP/IP messages it does not matter whether your client is
- Embedded
- Windows PC based
- MAC based
- Linux based
Reading data
Every time our controllers receive a reading from one of our meters, be it from a Smart Socket or from a Smart Meter, it transmits an ASCII message on port 53005 using a UDP broadcast. This means that to pick the message up you have to write a UDP listener that will listen to port 53005 on UDP and then parse the incoming information. Because of the broadcast nature of the message and the fact that it is simple ASCII text, our experience to date is that this is a very robust and simple protocol to use.
If you use the Energy Manager Desktop Edition for Microsoft Windows you can click on the "Debug" tab and see this information from the controllers. A typical screenshot of this is shown below.
Events are always in ASCII and each event is terminated by a carriage return character (ASCII 13). To access the meter readings, you need to ignore all incoming events except those that contain the test "Reading" for example:
These are the readings from the meters and take the form of ASCII text separated by colons (:)
| Name | Type | Example | Description |
| Controller Serial Number | 12 ASCII Hex Digits | 004A3BB5B04 | The serial number of the controller that sent this reading |
| Event type | ASCII text, variable length | Reading | The text "Reading" indicates that this is a meter reading |
| Meter Serial Number | 16 ASCII Hex Digits | 0021ED0000041319 | The serial number of the meter that is being read |
| Power | ASCII text showing a floating point number | 94031.992 | The power that the meter is consuming now in watts |
| Meter Channel | ASCII number, normally 1 .. 16 | 1 | The channel of the meter that is being read. Our 16 channel meters, for example, set this field to be 1 .. 16 depending on which of the meter channels is being read |
| State | ASCII number, normally 1 .. 99 | 1 | For Smart Sockets this field indicates the state of the internal switch. When 1 it means the socket is turned on and 0 indicates it is turned off. For non Smart Socket products this field should be ignored. |
Controlling Smart Sockets
To control smart sockets you should send an ASCII command over UDP to the controller on port 53004. The simplest way of doing this is to use a UDP broadcast although you might find it easier to use your own system. The command should be of the form of an ASCII text line, separated by commas (,) and terminated by a semi colon (;)
e.g. To turn a Smart Socket on:
004A3BB5B04,0,0021ED0000041319;
e.g. To turn a Smart Socket off:
004A3BB5B04,1,0021ED0000041319;
| Name | Type | Example | Description |
| Controller Serial Number | 12 ASCII Hex Digits | 004A3BB5B04 | The serial number of the controller that should process this reading. If set to FFFFFFFFFFFF then all controllers will pick up and act on the message. |
| Event type | ASCII digit | 0 | 0 = Turn off |
| Smart Socket Serial Number | 16 ASCII Hex Digits | 0021ED0000041319 | The serial number of the socket to be controlled |
Tip: When you are first getting your code working, it is simplest to use the FFFFFFFFFFFF serial number for the controller. If you send a command to switch a Smart Socket to a controller that the Smart Socket is not joined to the command will simply be ignored.
Troubleshooting
If you get problems using this protocol, try using Enistic Energy Manager for Windows Desktop to have a look at the data flow over the UDP port. The single biggest problem you may encounter is that of firewalls. Some Windows PCs and network administrators block broadcast information over UDP ports and in which case you may have instances where your messages are apparently being ignored whereas in reality they are simply not reaching the controller.
One instance of this that happens in our own offices is that the Wifi system we use does not relay UDP broadcast information back over the wired network that the Smart Energy Controllers use. This is apparent when we use our laptops for sending commands to the controllers via their wifi connections. In such instances, it is simplest to plug the laptop into the local network and everything then works correctly.
Getting further help
If you would like some help in getting this API working for you, please use the forums as the first point of call as they are checked regularly by a large number of people. These people may (or may not!) be able to not only help you with your problem but may also be able to provide sample code for you to help you out. Failing that, contact us in any of the usual ways: contact us.
