View source for Internet of Hamsters

[[File:meet_Ilya_and_pjotr.jpg|right|320px|border]]Meet Pjotr and Ilya, our Siberian dwarf Hamsters. Pjotr and Ilya are brothers and about a year old now. They get along reasonably well for two males living in the same cage. They like scrounging for hidden sunflower seeds in their cage. At night, they enjoy doing some exercise on their 3D-printed hamster wheel.

Oddly, and conveniently as we shall see, they have their own preferred orientation when running in the wheel. Pjotr likes to run to the left, while Ilya likes running to the right.

This running around at night is all good and well, but it does mean that I have no idea how much they are using the hamster wheel. This kept nagging me. Wouldn't it be nice to automatically keep track of all hamster activity and at my own leisure review their fitness? Luckily, by standing on the shoulders of the giants of open source software and low-code frameworks this is solvable without too much technical hassle (though programming and soldering was still required).

==Statistics==
For those in a hurry, the TL;DR: My two hamsters run at an average speed of 2.5 km/h; They reach a top speed of 4.9km/h and combined they run for about 3.5km each night (range so far is between 1.5km and 6km per night). The wheel is used almost exclusively between 1am and 5am.

==Overview of the system==
* A sensor on the hamster wheel detects rotations, the direction of the rotation and the speed (or the time between full rotations).
* When the wheel rotates, periodic updates will be send as MQTT messages on a preconfigured topic. The MQTT messages should note the direction of rotation, the rotation count and the average time for each rotation (indication of speed).
* A node-red data flow listens to the MQTT messages, adds time stamps and inserts the data as documents in an elastic search index
* That same data flow will retrieve the total distance traveled (the sum of all rotations found in the elastic indexes) and send an update message to a display device that shows total distance traveled and current speed.
* A Kibana dashboard shows the statistics, such as total distance traveled, maximum and average speeds, etc.

The following image shows how the different components work together to get the dashboard and display.

[[File:system overview.png|border]]

The display is not updated directly on the wemos, but instead is updated through a longer and slower cycle via node-red and elastic. This was for two reasons:
* The total distance is persisted in elastic search only, which avoids hard decisions on when to write the totals to persistent memory.
* The wemos is unaware of the radius of the hamster wheel, so all conversions from rotations to meters are done in node-red (javascript).

Let's list the technologies used in this system:
* [https://wiki.wemos.cc/products:d1:d1_mini Wemos D1 mini] (clone) for a wifi-enabled microcontroller module
* [https://www.letscontrolit.com/wiki/index.php/ESPEasy EspEasy] firmware as a low-code solution to connect the hamster wheel to the network
* [https://mosquitto.org/ mosquitto] MQTT brokers the data that comes from the wheel
* [https://nodered.org/ Node-Red] is used to route MQTT data to several destinations and to do initial processing on it
* [https://www.elastic.co/elk-stack Elastic Search and Kibana] are used to store all hamster wheel events and to show dashboards

==Hamster Wheel &ndash; Mechanics==
The hamster wheel itself is fairly simple. The design was based on [https://www.thingiverse.com/thing:1083729 work found on Thingiverse]. Three important differences:
* The diameter is as high as will fit on my build plate;
* To save space, the wheel is attached to the cage itself instead of having a separate base;
* The wheel *needs* to have the names of the hamsters (in alphabetical order).
Because the Thingiverse model was only available as a solidworks model, I decided to design my version from scratch as an [https://www.thingiverse.com/thing:3474019 Openscad model].

[[File:Hamster wheel model.png|600px|border]]

Originally, the wheel was used just like that. The idea of adding a sensor came up later, that is why the magnet was just glued to the back.

[[File:Wheel with magnet and sensor.jpg|600px|border]]

==Dual Pulse Sensor==
Because the hamsters run in different directions, it would be nice to detect the direction of rotation. To that end, a magnet is glued to the back of the wheel and two hall effect sensors are placed "asymmetrically" on the path of the magnet. This way, the relative timing of the pulses of the sensors indicate the direction the wheel is turning.
[[File:Sensor diagram.png|border|left]][[File:Pivot assembly.jpg|400px|right]]
The sensors are placed on the pivot assembly to properly align them on the path of the magnet.

==Contributions==
* [https://github.com/DannyHavenith/ESPEasy/tree/asymmetric_dual_pulse Fork of ESP Easy] that implements dual asymmetric pulse device
* [https://www.thingiverse.com/thing:3474019 3D files] for hamster wheel, pivot with integrated sensors and housing for Wemos.