Introduction to the experiment editor

phyphox
37 followers
Dec 9, 2022
This is an introduction to our experiment editor.
More info on http://phyphox.org
Twitter: https://twitter.com/rwth_phyphox/
Facebook: https://www.facebook.com/phyphox/
In this video I will explain how to create your own experiments for FIFOX.
Currently there are three ways to create experiments. The first and most obvious one
is by creating one within the app. On Android this is done with a big floating button in the
bottom right corner while on iOS this is done with the button in the top right corner.
In these simple experiments you can only record data from different sensors at a given rate.
There is no data analysis. If you set the rate to zero the data will be acquired as fast as
possible while any finite rate will tell FIFOX to average the sensor data to achieve your given rate
in samples per second. This function is nice if you just need to record data for later analysis
but if you want descriptions, icons, your own layout and real data analysis in the phone
you need one of the other two options. All experiments in FIFOX are defined in FIFOX files
even the ones that already come with FIFOX. In fact you will see later that you can also
change the existing experiments to achieve what you want without starting at zero.
A FIFOX file is just a text file that defines all properties of an experiment using XML.
XML is a very common language to structure information and if you are familiar with
XML you may want to create your experiments by directly writing your file in a simple text editor.
The FIFOX file format is completely documented in the FIFOX wiki which you can find on FIFOX.org
but to get an idea on how FIFOX experiments work in principle you might still want to
watch this video as the editor presented in this video is just a visualization of the XML file
and almost everything explained here also applies to writing XML directly.
And so this is the third option which is probably the most suitable for most of you
or visual experiment editor which you can also find on FIFOX.org.
In this video the editor might look slightly different and a little bit more cramped than
on your browser. This is simply because I zoomed in a little to make sure that the viewers watching
this video at a lower resolution can still see what I am doing here. First let's have a look
at the two buttons at the bottom. Download experiment lets you download and hence save
your work when you are done while load experiment lets you load your FIFOX file again.
Actually when I press load experiment you see that you can either drag your own file into the
dashed rectangle or you can pick one of the experiments that come with FIFOX. So if any
of our experiments is similar to what you want to do just press the button and change it to your
needs. But for the sake of this tutorial let's stick with the empty experiment. At the top you
see different tabs to which I will give you a short tour. They all represent different aspects
of your experiment. The first one is main. This contains generic information about your experiment
like the title, an icon or a description. You can hover your cursor above any of the
question marks to get more information and details about each of the settings.
You will also note the translation button next to most text fields. Here you can enter the text
which should be shown in a different language if you want to translate your experiment.
If you do not want to translate it just ignore these buttons.
As an example I will recreate a simple version of the experiment role where we take the input
of the gyroscope and calculate a velocity with the radius of a role given by the user.
So let's enter a name and the category mechanics. There is also another box in the main tab named
analysis options. These determine how often FIFOX should analyze your data. By default FIFOX will
analyze your data all the time which means that it takes all recorded data, applies the calculations
which we will discuss later and when it's done it will just start the calculations again on the
current data. This is good for most experiments but sometimes you want FIFOX to wait a moment
or only do calculations when the user has changed a setting. Examples for this are acoustic experiments
where the setting sleep is used to wait until enough data has been recorded to the microphone
or the tone generator experiment which does not record anything from the sensors
so the setting on user input tells it to only redo its calculations when the user
changes the tone frequency. For our role experiment we can just leave it at the default values.
Next stop the input tab. Here you can define any source of data that goes into FIFOX.
At the moment of this recording these are audio which is the microphone, sensor which is any of
the phone sensors like the accelerometer or the gyroscope and bluetooth which is a bluetooth device.
Note that the bluetooth function is still under development. So for the role experiment I choose
sensor and add it to our experiment. You can of course add more than one input but for this
experiment we only need one. Each type of input has different settings which again I explained
if you hover your cursor above the question marks. A rate of 25 hertz should be fine and averaging
is a good idea here. Be careful when using a rate of zero or very fast rate because some phones might
be slower or faster than you expect so the same experiment might work a little different on each
device. The output tab is very similar. Only this time you define any device to which FIFOX should
send data. Currently there is only audio which is the phone speaker and again bluetooth which is
still under development. So at the moment unless you want to make a noise to the speaker you
probably don't want to add any output to your experiment. In the next tab called views you can design
the interface for your users. The FIFOX interface consists of different elements which are placed
in different views. In the actual app a view is shown as a tab. The original role experiment has
two views. One is called velocity and the other one is called raw data. The raw data view only has
one element which is a graph showing the y-axis of the gyroscope. The other view velocity has three
elements. An edit element allowing the user to enter the road's radius and two graphs giving the
speed over time a meter per second and kilometers per hour. In the simple example we will leave out
the kilometers per hour graph. Currently there are four different types of elements. Info just
displays simple text to the user. Value shows a single value and if it's connected to a source
with multiple values it will show the last value. Graph obviously shows a graph and edit is an input
field where the user may enter a value which is used in the calculations. Like in our case the
road's radius. Each element has individual settings and there are way more settings than we can cover
in this video. So once again explore them by hovering over the question marks. Now we get to
the tricky part where the inputs outputs and the views are connected with some math in between in
the analysis tab. You will notice that all the elements we have added before are already here.
We have a sensor input, we have an edit field and we have two graphs one for the raw data and one
for the speed. If you click on the name they will expand so you can change the settings here.
You will also notice that the graphs have plus signs at the top of them. This is where you can
put data into the graph. In contrast you cannot put data into the sensor or the edit field which
is why they do not have these plus signs. Instead they have lines to the right because you can get
data from them. Each line is an output. If they are gray they are not used. To use an output you have
to attach a buffer. To do so click on the gray line. We want the y-axis of the gyroscope so let's try it.
Now click create and the line turns orange. If we click the line again we get some options for the
buffer. The name is just an internal reference. You may pick anything that helps you remembering
what you are doing in this buffer. If you use a name twice however the editor will eventually add
numbers to distinguish the buffers. The complicated part is the buffer size. Think of the buffer as a
long list of numbers. New values are always added at the end of the list. If the list gets longer
than the length the first value is removed when a new number is added to the end of the list.
So the length of the list remains the same. If you set buffer size to one you can only use the latest
number in your calculations. For a simple experiment without heavy calculations there's a special
setting which is zero. This makes the buffer infinite. But you should only use this for simple
experiments as this may quickly get heavy for older phones when the data just keeps piling up.
The other setting static is less important. You can enable it if the values in the buffer never
have to be calculated a second time. For example if they are purely calculated from constants
or not from sensor data or user input. Let's also add a buffer for the time output of the gyroscope
and connect them to our raw data graph. When we click on the plus sign of the graph we can choose
the data source. Here it should be a buffer. The alternative value would allow us to enter a single
constant number. We can click on the button below and then on the buffer we want to use. The button
now shows the buffer name and we can confirm our choice with okay. Now you can see that the buffer
is connected to the graph. We also need to connect the time data. The second graph is a little bit
more complicated because we need some calculations to get the speed. We want to multiply the angular
velocity from the gyroscope with the radius entered by the user. So it's time to use the insert button
between our elements to add a multiply module. Once again there are way more modules and options
than we can cover in this video. If you are looking for a specific mathematical operation
have a look at our wiki to learn about the existing modules. And if you need something
that is not in here send us an email and we will add the function. You will notice that the multiply
module has the plus buttons as well as the lines to the right. Obviously you put data in and get a
result out. So let's connect the gyroscope and the edit field to the inputs and connect the result
to the graph. Again we need the time data as well. But there is something different here. The input
menu as well as the buffer menu have an additional option called clear. And these can be quite
complicated and are a typical source for error. Without any clear enabled Vifox will always keep
adding data to the buffers. Just like you expect it from the gyroscope. As an example you do your
calculations on the first five values from the sensor and append them to the buffer going through
the speed graph. The calculations are done and Vifox starts calculating again. This time there
are the first five values in the buffer as well as new five values which have been recorded during
the first round of calculations. So Vifox will calculate the data again for the first five values
and then for the five new values and append them all to the buffer going through the graph.
But this buffer already has five values from the last round. So we end up with 15 values of which
the first five repeat. This is confusing and not what we want. So there are two options. Option one
is enabling clear on the input. So the gyroscope buffer is cleared when reading it as a source for
the multiplication. This way the buffer containing the data from the sensor is empty after reading it
and in the next round will only contain the new data. Sometimes this is exactly what you want.
But here we still need the data for the raw data graph. We could copy it to a different buffer
first but there is a better solution. So in option two we clear the buffer to which we write the
results of the multiplication. The drawback is that we will recalculate all the data each time
but a single multiplication is not such a heavy task. The buffer going through the speed graph
will always contain fresh values corresponding to the values in the gyroscope buffer and
also quite important the time buffer from the gyroscope. Okay so in principle our experiment
is ready now. Of course we need to label the axis of the graphs, add a unit to the edit field and a
few things could be done nicer. But in principle it would work. But there is one more tab which we
should not forget. The export tab defines which data should be saved if the user exports the data.
On complex experiments we do not want to save every buffer with intermediate data so you have
to tell FIFOX which data is relevant. The export is structured into different sets.
You can think of each set as a collection of data that can be presented in a single table.
In our experiment all the data has a common x-axis which is the time data from the gyroscope.
But if this was not the case you would need multiple tables to present your data.
So when exporting as a CSV file each set would be exported as an individual file.
Or when you export in the excel format each set would be a different worksheet within the excel
file. In our case we only need one set and we want to export the time, the raw data from the gyroscope
and the calculated velocity. Now we are really done. The last tab just shows us the source of
the generated FIFOX file which may be helpful to learn XML or check for errors but otherwise you
can ignore it. Just click download experiment and you get the FIFOX file. You can copy this
file to your phone or distribute it to other users. Okay so I hope this was a helpful introduction to
custom FIFOX experiments. If you want to learn more you can open the existing experiments in
the editor or check out our wiki on FIFOX.org. Also we would be happy to hear from you if you
come up with an interesting experiment and we would also enjoy to add it to our app if it is
of interest to a wider audience. Now have fun and create your own experiment.
