Skip to content
Hyperion is a system that observes a 'Smart Energy Meter'
Scala Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
app/src
docs
integration-test/src/test
project
scripts
test-app
.gitattributes
.gitignore
LICENSE
README.md
build.sbt
stryker4s.conf

README.md

Hyperion

Hyperion (Υπερίων) was probably the god of observation in ancient Greece. Fast-forward to the present, Hyperion is a system that observes a 'Smart Meter' system. Using Hyperion you can read your smart meter from your computer or Raspberry Pi. To do so, you need a connection between your smart meter to the computer. The smart meter has a P1 port, which is in fact an RJ11 connector. You can connect to the serial port or the USB-port as long as your operating system supports reading from it. On a Raspberry Pi, using a RJ11-to-USB cable, the serial port will become visible on /dev/ttyUSB0.

Design

Hyperion is built as an actor system and implemented with Akka. The main actors are:

  1. The MeterAgent creates the IO(Serial) extension (from akka-serial); it starts it and reacts to the messages it sends.
  2. When a Serial.Received comes in, the MeterAgent converts its payload to an UTF-8 string and sends it to the Collecting actor.
  3. The Collecting that collects pieces of data coming in until it thinks there is complete P1 Telegram. It then parses the content of its buffer using the P1Parser (not an actor). If that succeeds, it sends the telegram using TelegramReceived to the MessageDistributor.
  4. Actors that want to do something with the data subscribe themselves for incoming telegrams by sending RegisterReceiver to the MessageDistributor. All actors that are subscribed will receive the TelegramRecived messages that the MessageDistributor receives from the Collecting actor.

There are also some actors that process data from the smart meter:

  1. The RecentHistoryActor keeps a limited buffer of received telegrams. Using that buffer, it can report on the last 30 minutes (for example) of energy usage. Useful for seeing how a certain device influences energy usage.
  2. The DailyHistoryActor will schedule itself to sleep when it starts, and awake at a fixed time once a day. It will then wait for one TelegramRecived, log some metrics in a database and go to sleep again. Useful for generating daily/monthly/yearly reports.
  3. The ActualValuesHandlerActor is created once a WebSocket is connected at its endpoint. From then on, it will pass on all TelegramRecived to that WebSocket. Useful for having a "life" view on the energy meter.

Web App

There is also a web front-end to Hyperion. It is maintained in a separate Git repository.

About the code

Hyperion is written in Scala using the Akka-framework.

Circle CI SonarCloud quality gate SonarCloud vulnerability count SonarCloud technical debt Mutation testing badge Scala Steward badge

Getting Hyperion

Pre-built Debian packages can be downloaded from CircleCI. Click on the latest green build and move to the 'Artifacts' tab. The packages are located in the deb folder.

Hyperion integration tests

The integration tests are written using Rest Assured and stored in ./src/it/. Test data is injected using an SQL script (found in ./scripts/database).

To run the tests locally, issue

sbt \
    -Dconfig.file=app/src/test/resources/environment.conf \
    integrationTest/test

License

Hyperion is licensed under the MIT License. See the LICENSE file for details.

You can’t perform that action at this time.