This repo holds everything needed to breathe life into a MIROSLAV device - MIROSLAVino Arduino firmware and Record-a-SLAV, a Python data acquisition script. MIROSLAV firmware was built to be used over a network, with the MQTT protocol, enabling scalable remote data acquisition from hundreds of cages. The MIROSLAV device is also equipped with environmental sensors.
Hardware designs can be found in the MIROSLAV-hardware
repository. A complete, user-friendly MIROSLAV software toolkit for analysis of MIROSLAV data, from raw data to statistical analysis, can be found in the MIROSLAV-analysis
repository - also contains an example dataset of real data recorded in our lab.
MIROSLAV (Multicage InfraRed Open Source Locomotor Activity eValuator) is a platform for non-invasive monitoring of circadian locomotor activity in laboratory rodents. MIROSLAV is fully open source and scalable to hundreds of cages. All of its hardware and software components are described in the paper: https://doi.org/10.1101/2024.06.25.600592
To make full use of MIROSLAV's potential, you need a Wi-Fi network (which does not need to be connected to the Internet) and a computer.
-
To set up a Wi-Fi network, you can use any Wi-Fi router - just power it up and connect your computer to it.
-
It is advisable to set up a static IP address for your computer to ensure it won't change - if it does, MIROSLAV's configuration needs to be updated as well.
-
Set up an MQTT broker on your computer.
- Mosquitto is one of the most widely used brokers. Once installed, these two configuration options need to be added to
mosquitto.conf
:
allow_anonymous true listener 1883 0.0.0.0
Password authentication is also available and MIROSLAV supports it, but it's a bit more work to set up.
-
On Windows: By default, the config file's location is
C:\Program Files\mosquitto\mosquitto.conf
. Briefly, after you add the configuration changes and reboot, you should have it up and running automatically. You can also not reboot, and instead open up Services (a Windows built-in tool), scroll down toMosquitto
, right-click and selectStart
. The broker IP address inconfig.h
is then the IP address of your computer. You can find your IP address by opening up Command Prompt and typingipconfig
. -
If you don't want it to autostart every time you boot, in Services, right-click on
Mosquitto
, selectProperties
, and underStartup type
selectManual
. This way, it will only start if you manually start it fromServices
. -
On Linux, it's usually as easy as installing Mosquitto using your package manager (on Ubuntu, and likely many other distros, the package is called
mosquitto
), setting up the config (the config file's location is/etc/mosquitto/mosquitto.conf
by default) and runningsudo systemctl start mosquitto.service
(replacestart
withstop
to terminate the broker). If you want it to start on boot, runsudo systemctl enable mosquitto.service
, and to disable autostart on boot, replaceenable
withdisable
in the previous command. You can check your computer's IP address by opening up a terminal window and runningip addr
.
- Mosquitto is one of the most widely used brokers. Once installed, these two configuration options need to be added to
-
Set up your network options and other MIROSLAV device parameters
config.h
and upload MIROSLAVino to your MIROSLAV device. -
Start Record-a-SLAV. If you do not have Python and use Windows, we prefer WinPython to get an easy-to-setup Python distribution. Be sure to install the
paho-mqtt
library usingpip
.
Additionally, once you power up your MIROSLAV, you can access it via its IP specified in config.h
and upload code with a changed configuration remotely:
- In the Arduino IDE, click
Sketch > Export Compiled Binary
. - In the MIROSLAVino directory which holds the
miroslavino.ino
program, abuild
directory will appear. Inside it should be one directory,esp32.esp32.esp32s2
, with multiple files - we will needmiroslavino.ino.bin
. - In the address bar of your web browser, type in MIROSLAV's IP address as specified in
config.h
. - In the interface, navigate to
miroslavino.ino.bin
, select it, and upload it.
After a few minutes, your MIROSLAV should be running the updated code.
- Arduino core for the ESP32-S2 - Briefly, in Arduino IDE settings, add the additional boards manager URL
https://espressif.github.io/arduino-esp32/package_esp32_index.json
, installesp32
by Espressif Systems in the boards manager and selectESP32S2 Dev Module
in the boards menu. (tested with v3.0.1)
How to install Arduino library?
AsyncMqttClient
by marvinroger (tested with v0.9.0)BH1750FVI_RT
by RobTillaart (tested with v0.3.1)
paho-mqtt
-
We should improve the setup instructions and code documentation - contributions (via the e-mail listed in the MIROSLAV paper or via a pull request) are welcome.
-
Password authentication setup instructions for Mosquitto.
-
Done (v0.5) -
MIROSLAV device has two onboard sensor modules: HDC1080 (temperature, humidity) and BH1750 (illumination). We are currently working on implementing their functionality in the code. The functionality for an additional PIR (attached to the onboard ENVPIR connector) to monitor human entries into the habitat room is implemented. -
Done (v0.5) -
Make it easier to use an arbitrary number of input serialisation boards on the stack.
MIROSLAV-hardware
- Everything you need to construct the MIROSLAV device and start monitoring hundreds of rodents' locomotor activity patterns 24/7 in their home cages.mirofile
- Your buddy for dealing with raw MIROSLAV data. A Python library used by Prepare-a-SLAV to parse raw MIROSLAV logs into a dataframe.MIROSLAV-analysis
- A complete, user-friendly MIROSLAV software toolkit for analysis of MIROSLAV data, from raw data to statistical analysis. Also contains an example dataset with real data recorded in our lab.
You can modify any part of MIROSLAV freely under the GPLv3 license - if you have any questions, problems, or ideas on how to improve MIROSLAV, feel free to reach out to us, submit a GitHub issue, or a pull request.
The MIROSLAV logo is created by Petra Šoštarić Mužić and licensed under the CC BY-NC-SA 4.0 license - more details can be found in the repository's logo/
directory.