FREE (0.3.0)
Functions documentation
FREE_Web
RPi_Proxy
interface.py(RPi_Proxy)
How to install
Pre-requisites
Main server
For FREE_Web:
- Git (2.30.2+)
sudo apt install git
- Python (3.7.0+)
sudo apt install python3 sudo apt install python3-pip
There are need more installation but on the repository, you will have a "REQUIREMENTS.txt" that you will run to install them.
For the video server:
- Janus
sudo apt install snap sudo apt install snapd sudo snap install janus-gateway
For tools to test:
- Flask
pip3 install flask pip3 install flask_cors
Rasberry Pi
Operating System:
- Raspbian GNU/Linux 10 (buster)
For the Proxy it self:
- Python (3.7.0+)
sudo apt install python3 sudo apt install python3-pip sudo apt install python3-venv pip3 install pyserial
- Git (2.30.2+)
sudo apt-get install git
For the video stream:
sudo apt-get install gstreamer1.0-tools sudo apt-get install gstreamer1.0-plugins-good sudo apt-get install gstreamer1.0-plugins-bad sudo apt-get install gstreamer1.0-plugins-ugly sudo apt-get install gstreamer1.0-plugins-base
Main Server (FREE_Web)
This software is the dispatcher of the information. By allowing the communications from the frontend and each RPi_Proxy responsible for an experience. To install this you need to install at least Python 3.7.
Then go to the project on github https://github.com/e-lab-FREE/FREE_Web and follow the steps of installation that we present there.
After the installation you will have the version of FREE 0.3.0 with a database and HTML page configured for a pendulum experiment as follow:
After confirming that this initial installation of FREE is run as expected (you obtained a similar page as shown above on your webpage), you can install a video stream serve if your experiment has a video camera connected to the computer, this computer needs to be able to connect to the main server via the internet (VPN, ...).
Janus stream server
To install the Janus stream server you will need to run the following commands on your Debian 11 machine:
sudo apt install snap
sudo apt install snapd
sudo snap install janus-gateway
After the installation of the Janus you will need to go to the folder of the configuration of Janus by:
cd /var/snap/janus-gateway/common/etc
and make delete every file that is not in this list: "janus.jcfg", "janus.plugin.streaming.jcfg", "janus.transport.http.jcfg" and "janus.transport.websockets.jcfg".
Then edit the "janus.plugin.streaming.jcfg" and define an administration secret by uncommenting line 104. After that define the possible ports that Janus will use to receive the video stream from the source by uncomment line 106and put "rtp_port_ranges" for example to 6000-7000.
After this, you can delete the sample endpoints by deleting all lines from line 124. And your Janus installation will be completed after restarting the Janus process by running the command:
sudo snap restart janus-gateway
Now to add new video stream ports before you will need to go back to your home folder and clone the repository:
git clone https://github.com/e-lab-FREE/Video_Tester.git
inside of this repository, you will find two python files for now we will focus on the "janus_tool.py", run it by typing the command:
python3 janus_tool.py
you will get the following interface on your command line:
By pressing "N", you can give a name to your stream and a description (this area just to help you distinguish the different streams).
After filling the info you will get a port and an ID as shown in the image above. This will be important when you will setup your RPi_Proxy.
Raspberry PI (RPI_Proxy)
First checkout the project from github (https://github.com/e-lab-FREE/RPi_Proxy), and you can get the code using:
$ git clone https://github.com/e-lab-FREE/RPi_Proxy
After following the installation guide on the github, you will get a version of the RPi_Proxy that is able to communicate with a pic experiment and it is configured in particular to communicate with a pic that performed a Pendulum experiment, for changing the experiment the only thing you need is to change the "experiment_details.py" on the pic_intreface folder. We have some of these files for different experiments such as the Langmuir on the following repository: pic_interface.
It's possible to connect experiments that are not controlled with a pic, for example, we have on e-lab an experiment controlled by a Rasberry Pi. To do that it was needed to change the code on the "interface.py" but the name of the function need to be maintained. The code for this RPi_Proxy is presented on the following github: Cavity.
Video capture and stream
This information is also on the github so if you follow all the github README.md of the repository "RPi_Proxy" you can sick this section.
So after getting the Repository of the Proxy from here you will get a file called "start-video.sh" with the following structure:
#!/bin/bash video_server= 0.0.0.0 video_port= 6000 usb_camera=/dev/video0 video_width=1280 video_height=720 video_frame=30/1 killall gst-launch-1.0 gst-launch-1.0 v4l2src device=$usb_camera ! video/x-raw,width=$video_width,height=$video_height,framerate=$video_frame ! clockoverlay time-format="%x - %X" ! videoconvert ! omxh264enc ! h264parse ! rtph264pay config-interval=1 pt=96 ! udpsink host=$video_server port=$video_port async=false
so where you will need to put the port that you configured on the "janus_tool.py" for your experiment. And the video_server with the IP of your video server. One more thing needs to be checked on the "start-video.sh", the USB port where ur camera is connected, the resolution of it, and the frame rate.
To check your resolution and USB connection these commands may help:
v4l2-ctl --list-devices
v4l2-ctl -d /dev/$your_dive$ --list-formats-ext
After this you can run the following command to start the stream:
sh start-video.sh
Accessing the stream
After putting the start-video.sh process on you can go back to your video server and run the "janus_view_streams.py" this tool will help you to check if your webcam is streaming to the server. The "janus_view_streams.py" is a simple flask server that will run on your ip on the port 5001, if you don't want to run this tester on this port in particular you will need to edit the last line of the "janus_view_streams.py":
app.run(debug=True, host= '0.0.0.0', port= 5001)
and change there the port.
After running the command: python3 janus_view_streams.py you will get the following page:
And if you click on the second option you should be able to see your stream like this:
How to add new experiments
The first one has to have an experiment programmed in a controller of such experiment, after that and after installing the Proxy on a computer capable to communicate to the main server, the developer of the experiment needs to create the following entries on the database: Protocol, Experiment and Apparatuses.
Experiment
To create a new Experiment on the database is just click on the "+" on the left of the pag.
By doing that you we get to a similar pag as the above, so you need to fill the information about your experiment:
Name-> with the some of your experiment;
Slug name-> the name of the html file of your experiment (explain on the section ...);
Description-> the particular html with the description of the experiment, with the information that the user need to understand it;
Configuration-> is a JSON with basic information that the Proxy needs to know about the experiment such as the serial port that is connected (for example in the case of the experiment Pendulum);
Scientific area-> what area is the experience integrated;
Lab type-> the background needed to execute the experiment (basic, intermedium, advance).
Protocol
After finishing your Experiment you need to create a new Protocol to do that again click on the "+" next to the Protocols tab on the left.
Every Experiment should have at least one Protocol. A Protocol is a way to describe the parameters that a user can select and modify to run an experimental execution. One physical setup of an experimental can do different execution with different initial parameters so that is why one experiment can have multiple Protocols.
You will have a page like the one shown above that you will need to file:
Experiment-> select your exeperiment;
Name-> with the name of the protocol, this name should be descriptive of the experimental setup that the controller will use. That you can translate;
Configuration-> this is a JSON schema that will test the inputs that the user will give, and check that their configuration are within the range of the experiment ( You can do your JSON Schema here).
Apparatuses
After programing the Protocols one last thing needs to be done on the database. You need to provide to the database the information of the Apparatus (the computer witch will connect to the FREE_Web).
You will have a similar page as a shown above, so you need to fill the follow information:
Experiment-> the one experiment that apparatus is connected to;
Protocol-> the protocols related that Experiment;
Location-> Location of the experiment;
Secret-> the password that you need to configure and the "server_info.ini" on the RPi_Proxy;
Owner-> the person responsible for the maintenance of the experiment;
Video Configuration -> the ID that the Port of the stream of the video is connected to the server of Janus (explained in the section ...).
HTML/JS
With the FREE installed you will have the following page to run an experiment Pendulum, basically it starts with a discretion that is on the database:
Then you can go to the Configuration tab and set up the initial condition of the experiment, and after Save and Submit the configuration
you will be sent to the tab Execution where you will be able to see the video stream and the plot of the data sent by the experiment.
To finalize the process of creating a new experiment and adding it to the FREE you will need to do an HTML and JS similar to the one that we provide for the Pendulum experiment. Basically, you will need to add as much inputs on the Configuration tab, and change the JS that is plotting, and put the data point on a table so it displays the data points of your experiment.
After you make sure that everything is working as intended you need to add the HTML fill on the "/free/templates/free/experiments" folder and make sure that the name of the file is the same as the Slug that you put on the database ($Slug_name$.html) and the JS, image and CSS file that you need to display the HTML you will need to add them to the respective folders on the folder "/free/static/free".