Implementation details

Once running, the homecage system should be simple to use. Yet, for this simple system to work, a number of independent components must each work and must communicate with each other. As is often the case, the implementation details to create a simple system is complex. Two cliches to describe this is 'you can't fly with half a wing' and 'the devil is in the details'.

We have about 15 components in use! Each component is developed independently and all are open source. It is amazing that this system works? What follows is a description of the different pieces of the homecage system with links to the source code and the components that are used.

Raspberry Pi system

Don't forget the Raspberry Pi! It is open-source hardware made by the Raspberry Pi Foundation. It is running a variant of the Debian operating system called Raspbian.

Documentation

This website is written in markdown. The markdown and a description of the contents using yaml are brought together, compiled, and a static site is generated by mkdocs. The final layout is controlled by an mkdocs theme called material.

Front end

  • index.html - Main web interface written in html, uses Javascript and the Javascript Angular library to provide dynamic and real-time content.

  • videolist.html - Again, an html web page but this time using Jinja as a template engine. Jinja is default template engine used by Flask.

  • hello.js - Javascript code that implementes the logic of the web interface. Has functions that get called when user is clicking. Also has function to talk to homecage_app.py web server via a REST interface. This is not standard Javascript but is using the Angular library.

  • hello.css - A Cascading Style Sheet (css) text file that describes the precise layout of the web pages.

Back end

  • home.py - The python back-end that runs everything. This includes controlling DIO pins to turn lights on/off, running bash scripts to start/stop the video and to convert .h264 video files to .mp4. This code provides a clearly defined application programming interface (API) to all these components such that the web server in homecage_app.py has an easier job.

  • homecage_app.py - Python code that uses the Flask library to run the web-server and provide bi-directional control of the home.py back-end. In one direction, it accepts web url requests and sends them to the backend, in the other direction, it accesses the back-end and send information back out to the web clients. This primarily implements a REST interface so a client-side browser can get and set server values without explicitly logging in to the server.

  • config.json - A text file written in json that provides human editable configuration options for the server.

uv4l

avconv

  • convert_video.sh - Bash shell script to convert a .h264 video file into .mp4. Uses avconv function which is part of libav library.