The platform

Ethoscopes are modular, open-source tools. Anyone can build, modify or even sell them, as long as this is done in accordance with their licence.

A platform has three components:

1. one or more ethoscopes;
2. a wireless network;
3. a regular PC that receives data from the ethoscopes, called the node.

Ethoscopes work as a distributed system: each one tracks its own animals, so many can run in parallel and the node never analyses data. If the node or the network goes down while experiments are running, tracking continues, and the node collects the data once it is back.

Note

The files used to build the ethoscopes described in the 2017 PLoS Biology paper are archived on Zenodo. The platform has been maintained and changed since then, so build from these pages instead.

Services

Node and ethoscopes run their software as systemd services, so you can:

• check a service with systemctl status <name>;
• stop, start, restart, enable or disable it with systemctl <action> <name>;
• read its log with journalctl -u <name>.

Services and restarts shows how to reach each machine to do this.

On the node

The node usually has the fixed address 192.168.1.2 on the ethoscope network. It runs:

• ethoscope_node.service, the web interface on port 80, from which ethoscopes are found, started and stopped;
• ethoscope_backup_unified.service, which copies the result databases and video chunks from every ethoscope to /ethoscope_data with rsync (the same work can be split between ethoscope_backup_sqlite.service and ethoscope_backup_video.service);
• ethoscope_update_node.service, the update server on port 8888, which updates the software of the node and of the ethoscopes;
• a git mirror of the ethoscope repository, from which the ethoscopes update;
• a time server, so that all ethoscopes share the node’s clock.

On each ethoscope

• ethoscope_device.service, a web server on port 9000 that exposes the ethoscope’s status, snapshots and tracking data. It is normally reached through the node.
• ethoscope_listener.service, which starts and stops tracking and video recording. Keeping it separate from the web server means the web server can restart without interrupting an experiment. Tracking happens on the ethoscope itself, in real time.
• ethoscope_update.service, which applies updates pushed from the node.
• A database for the results. Ethoscopes write SQLite files by default; images made before late 2025 used MySQL/MariaDB (see Data saving and backups).

Ethoscopes fitted with the GPIO PCB shield also run ethoscope_GPIO_listener.service and ethoscope_light.service.

On the router

The router gives the ethoscopes their addresses by DHCP and keeps a reserved address for the node. See The network.

Building a platform

Building the hardware and installing the software for each component is covered in the Build section: the ethoscope, the SD card image, camera and focus, arenas, the network and the node.