ElWiz - a program to read data from Tibber Pulse

ElWiz - a program to read data from Tibber Pulse


- Signals to the program
- References

Intro

<code style="color:red">Breaking changes: Users with an existing installation of ElWiz are encouraged to carefully read the <a href="./docs/Breaking.md">Breaking.md</a> document</code>

Tibber Pulse is a microcontroller (MCU) capable of reading power consumption data from an AMS meter. In the following it is referred as Pulse. ElWiz retrieves data from AMS meters by using Pulse.

ElWiz is made for people who want to build a smart home without being dependent of external resources or cloud services. The purpose is to retrieve data from an AMS meter to use in Home Assistant, OpenHAB or a similar system.

The program interprets raw binary data from Pulse and translates it into easy understandable JSON format. The program does not use SSL, and it is therefore easy to use for those who have an extra PC, Raspberry Pi or their own server at home. The program is designed to run continuously 24 hours a day, and is therefore not suitable for running on a laptop or other machine that you like to switch off after use.

ElWiz can also run in a Docker environment along with an MQTT broker and Home Assistant. A separate Docker guide is is found here: docker.md

Users of AMS meters are billed per hour. The optional price tool (fetchprices.js, now a wrapper around the elwiz-prices npm module) retrieves spot prices from the Nord Pool power exchange. When price enrichment is enabled, ElWiz adds supplier/grid surcharges and cost calculations so downstream components receive spotPrice, floatingPrice, and fixedPrice. These features are disabled by default and are activated by setting computePrices / calculateCost in config.yaml. The price tool is described in detail in fetchprices.md.

elwiz-chart is a chart program that is used to visualize the fluctuating price data fetched by the fetchprices program. The program is described in detail in elwiz-chart.md document.

elwiz-chart

An elwiz-chart example showing two days of prices

ElWiz is written in node.js (javascript) for Linux and it is easy to install and use. A configuration file is available for individual adjustments. Those who want to use it on Mac or Windows may need to make some minor changes to the program. This possibly applies to signals which are described further down.

ElWiz is tested with only access to the Kaifa MA304H3E AMS meter. It is possible that some minor changes may be needed if it is to be used on an AMS meter from another manufacturer.

Below is described what you need to install ElWiz and set up Pulse. You can then send data to Home Assistant, OpenHAB, or similar systems. In Home Assistant mode ElWiz has builtin auto discovery

What you need

a Tibber Pulse
access to an MQTT broker
some knowledge of MQTT
be able to edit simple information in a text file

Nice to have but not required

access to Home Assistant or another similar platform
knowledge of programming in node.js (javascript)
MQTT-controlled coffee maker

Installation

For those who don't know git, it is easy to download and install from the ZIP archive here: https://github.com/iotux/Pulse/archive/master.zip Download and extract it in its own directory (folder). Users of git can use git clone as usual. The program needs write access to the directory.

The easiest is to use git clone to install the program:

git clone https://github.com/iotux/ElWiz.git

Then install the program with the following commands:

cd ElWiz

npm install

The following dependencies are thus installed

* axios
* express
* mqtt
* date fns
* xml-js
* node-schedule
* js-yaml

ElWiz configuration

The file config.yaml.sample is copied to config.yaml. If you install programs on the same machine as your local broker, you probably don't need to make any further changes in config.yaml. Otherwise, it will be necessary to enter the IP address and possibly the username and password of your own MQTT broker. The most important parameters in the configuration file look like this:

---
# Replace with your own MQTT broker
mqttUrl: "mqtt://localhost:1883"
mqttOptions:
  username:
  password:


# meterModel can be kaifa, aidon or kamstrup
meterModel: kaifa

# Tibber Pulse listening topic
topic: tibber

# ElWiz publishing topics
pubTopic: meter/ams
pubStatus: meter/status
pubNotice: meter/notice

# Publish options for list 1, 2, 3 & status
list1Retain: false
list1Qos: 0
list2Retain: false
list2Qos: 0
list3Retain: true
list3Qos: 1

statusRetain: false
statusQos: 0

# ElWiz event messages
willMessage: ElWiz has left the building
greetMessage: ElWiz is performing

# Tibber Pulse event messages
onlineMessage: Pulse is talking
offlineMessage: Pulse is quiet

# Debug mode at startup
DEBUG: false
debugTopic: debug/hex

# User has production (solar panels)
hasProduction: false

#############################################
# Pssible cacheType values
#   file
#   redis
cacheType: file

# Possivle storage type
#   mongodb
#   mariadb 
#   custom
#   none
storage: none

#############################################
# Possible publishing modes
#   hassPublish
#   basicPublish
#   customPublish
publisher: hassPublish

#############################################
# Publish to Home Assistant (defaults to TRUE)?
hassPublish: true
# Home Assistant sensor base topic (defaults to "elwiz/sensor")
haBaseTopic: elwiz

# Don't change the following topic unless you
# have changed the way HomeAssistant read
# MQTT messages
haAnnounceTopic: homeassistant


# Home Assistant sensor base topic (defaults to "elwiz/sensor")
# This is different from "pubTopic" to separate it from basic use of ElWiz
# A separate topic will also prevent "spamming" of HA
haBaseTopic: elwiz

computePrices: true
calculateCost: true

It is worth noting the following:

topic under # Listening topics must match what is specified in mqtt_topic when configuring Pulse. Other changes should not normally be required.

The program has "ready-made" integration for Home Assistant as configured. For other systems some configuration changes are likely needed. A plugin system is used to transform Pulse messages to other formats.

computePrices and calculateCost control whether ElWiz enriches spot prices with supplier/grid components and performs cost aggregation. Leave them set to false if you only need raw spot prices from MQTT; when set to true, ElWiz lazy-loads the price calculation module and will expect the surcharge-related configuration values to be present.

ElWiz chart configuration

The ElWiz chart program has its own configuration file chart-config.yaml. This makes it possible to run the program along with fethprices.js without running ElWiz. The file config.yaml.sample is copied to config.yaml. The default parameters should be okay unless you are runnung in a remote environment. If so, you will need to set the chartConfig wsUrl parameter to the IP address of your chart server (server.js). Furthermore, currencyCode and languageCode should be set according to your own currency and language.

---
# The chart server configuration
# Changes will need a server restart
serverConfig:
  debug: false
  savePath: data
  serverPort: 8321
  wsServerPort: 8322
  # MQTT params
  # Replace with your own MQTT broker
  mqttUrl: "mqtt:localhost:1883"
  mqttOptions:
    username:
    password:

  # Priceinfo topic
  priceTopic: elwiz/prices
  chartTopic: elwiz/chart
  # Home Assistant
  hassPublish: true
  haBaseTopic: elwiz
  haAnnounceTopic: homeassistant

  # Factor for calculating green/red zones
  # % added/subracted to/from average price
  # It is permanent until changed here
  fixedAverageOffset: 0.0
  # Used for multiplying the value from the
  # adjustLeftAvgOffset and adjustRightAvgOffset
  # MQTT messages
  adjustmentStepFactor: 1.0

  # Change according to your own language/country
  currencyCode: NOK

# The chart web client configuration
# Reload browser to activate changes
chartConfig:
  # Replace with IP address of server if running remote
  # The port number needs to be
  # equal to the "wsServerPort" above
  wsUrl: "ws://localhost:8322/"

  # Set this to "true" if you want
  # dark mode on mobile devices
  darkMode: false

  # Set true if you want the Y axis to start at 0
  yBeginAtZero: false
  
  # Web client debug
  debug: false

  # Change according to your own country
  languageCode: nb-NO
  currencyCode: NOK

Setup of Pulse

The first step to connect Pulse to your own network is to forc

ElWiz

Install / Use

README