Smart Fish
iTwin.js meet Home Assistant — Home Assistant meet iTwin.js
So, everyone talks about digital twins, but have you got one? By that, I do not mean a 3D scan of yourself, rather than a twin of your digital, connected home. IoT springs to mind here.
Back in 2017, I acquired my first “smart device”. Basically, an air quality monitor, reporting Co² level, PM2.5, humidity, and temperature. Other smart devices such as smart power sockets, light switches and more and more temperature and humidity sensors soon followed. Each device came with its own app, often (almost always) connecting to a public cloud for ease of access for the user. Of course, it also allowed the manufacturer to gather information about its users.
That’s when I started looking into implementing an open-source hub.
After a bit of tinkering with various systems, I settled for Home Assistant https://www.home-assistant.io/. Mostly because of the broad user base and great community but also because it provided a way to integrate all my existing gadgets.
Home Assistant offers very nice dashboard functionality and there are some amazing examples out there such as https://community.home-assistant.io/t/floorplan-ui-with-color-synced-lights/169417 or a nice collection can be found here https://community.home-assistant.io/t/share-your-floorplan/21315/18.
Adding a floor plan is relatively simple, and can be achieved without the use of expensive software. I never did that, partly because our apartment isn’t very large and partly, well, where’s the fun in 2D.
I always had the idea of somehow linking up sensor states magically to a 3D model. But the question remained; how can a non-programmer (like me) achieve this?
Enter iTwin.js
Bentley Systems recently launched an iTwin.js accreditation course and in a very accessible step by step course, Roop and Bao walk you through the process of creating a smart house! Just what I needed.
You can find the class right here (access code: RYZZWK).
Required files are on GitHub
To get an overview of the course head over to Roop’s blog post: https://medium.com/itwinjs/the-program-8234e332ac8a
iTwin.js https://www.itwinjs.org/ lets you enhance your already existing digital twin. But I didn’t want to make this too much about iTwins or Home Assistant, rather about the possibility to federate data in a way so it becomes easily accessible. I also want to use a personal account as this will demonstrate the ease of access.
In this 1st part, I want to describe the basic principles and what to expect. While I improve my programming skills and gradually build out the digital home, I will publish further parts going into more detail.
Here’s what you need
3D Model
First, you will need some sort of 3D model to host your devices. I had models of sections of our apartment sitting around, but never a complete picture.
You can get started with the course sample file. Most 3D models will work but for your smart devices, you need to add some parameters. There is also the option to draw rooms or spaces dynamically using iTwin.js but that would be a challenge to be tackled another time. For my purposes, I used Revit but can recommend using MicroStation as well. In case you are unfamiliar with 3D modelling tools, check out https://medium.com/itwinjs/classified-42733f8d1368
In Revit, I created a range of sensors as generic models. Of course, this can be extended to any Revit family such as electrical equipment or lighting fixtures. As “Type properties” I added SmartDeviceId and SmartDeviceType. This information will then be shown later in a table and is also used to link the sensor data stream to the device icon.
Bentley Account
You will need a Bentley account, which you can create for free at https://www.itwinjs.org/ -> Getting Started
iTwin Synchronizer
Next on the list will be the iTwin Synchronizer. It is a very simple to use application that can be downloaded for free https://www.bentley.com/en/products/product-line/digital-twins/itwin-synchronizer
Home Assistant
You need a running instance of Home Assistant. Getting started with the install is straightforward.
https://www.home-assistant.io/getting-started/
I started by running it on a Raspberry Pi but quickly switched to a virtual machine using Virtual Box and now Proxmox.
https://www.youtube.com/watch?v=vnie-PJ87Eg
https://github.com/whiskerz007/proxmox_hassos_install
In case you don’t have a spare Pi kicking around or don’t have a home lab, you can use cloud services like https://www.linode.com/. I haven’t tried this yet, but it could be a very interesting side project.
The code
Once that is out of the way you need to familiarize yourself with typescript. I am no pro here and I am still l̶e̶a̶r̶n̶i̶n̶g̶ struggling and for this exercise required s̶o̶m̶e̶ a lot of help. If you can, subscribe to the training course. If you are a pro and know what you do get the files immediately from GitHub
Moving along further
To spice things up a bit and to get real and live data we federate the iTwin with sensor data coming in from Home Assistant. In case your smart device gadgets haven’t arrived yet, Home Assitant out of the box already provides a bunch of states you can get started with.
For this to happen we are taking advantage of another npm package; Node-homeassisstant https://www.npmjs.com/package/homeassistant. This is required to add your Home Assistant data.
The standard npm package dumps all information into your browser, so I ended up with 1700 states coming from a wide range of entities.
Instead of wading through all these, we tweaked the code so that we get the Home Assistant data in a more structured way.
SmartDeviceAPI.ts
This will surface your device data in the browser.
Icons
In the accreditation course, we used icons based on the smartDeviceType. In this example, I used the cloudData.attributes.device_class. This allows me to add a bit more information about the IoT device itself. I used the SmartDeviceType to add a friendly name to identify the sensor. On top of that, I don’t have to add a new icon when adding a new temperature sensor.
Refresh
Most of the sensors in use, such as those for temperature and humidity, send out an update every few minutes. This is usually enough to trigger certain automations — such as turning on or off a fan or the heating. Some of the DIY sensors can be set to update every 10 seconds. For testing purposes, I set it first to 5 seconds but that turned out to be too frequent.
This will drop all decorators every 10 seconds and then add a new, refreshed set of decorators.
The Prototype
This now lets me monitor the temperature or current power consumption of my fish tank. Not to forget all the other sensors. What I do like about it — it gives me a great overview of the whereabouts of the gadgets.
I hooked this up to the internet under the close supervision of these guys.
Other possibilities
There is of course much more iTwin.js can do for you. Check out the examples on iTwinjs.org.
What’s next?
Once complete the 3D model can run alongside the wall-mounted tablet giving valuable insights into what’s going on. Touch functionality lets you spin the model around and explore every detail.
As an added feature I can imagine that the fish tank starts flashing if the temperature is out of range, giving a visual indication of what’s going on. iTwin.js also allows for light effects which could simulate lighting levels. I already an automation tracking cloud coverage and adjusting lighting levels accordingly.
The npm package also allows the integration of cameras and can trigger services. This enables a user to turn on a light switch.
Special thanks to Roop, Bao, Glen, and the Home Assistant developers.
Stay tuned!
