OLD Experiment editor (Archived)
This page is an archived explanation of the old webeditor. For information on the new blockly-based editor refer to experiment editor.
Warning: The editor has seen some updates since this text and especially the video was made. New instructions will follow, but the principles are the same, so please don't be put off by the different look and feel.
The visual experiment editor basically is just a wrapper for the phyphox file format. Refer to the documentation of the file format for details on any modules, parameters or options. Also, when using the editor for the first time, we highly recommend the introduction video as currently this articles is mostly a shorter transcript of this video:
- Introduction to the experiment editor on Youtube.
Contents
Overview
Currently, there are three ways to create experiments for phyphox. The first, and most obvious one, is by creating one within the app. In these simple experiments, you can only record data from different sensors at a given rate. There is no data analysis. 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 phyphox are defined in phyphox-files, even the ones that already come with phyphox. In fact, in the visual editor, you can load and change the existing experiments to achieve what you want without starting at zero. A phyphox-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 phyphox file format is completely documented in this wiki.
The third option is the visual experiment editor, which is probably the most suitable for most of you.
Save / Load
First, let's have a look at the two buttons at the bottom: "Download experiment" let's you download and hence save your work when you are done, while load experiment let's you load your phyphox-file again. Actually, in "Load experiment", you can either drag your own file into the dashed rectangle or you can pick one of the experiments, that come with phyphox. So, if any of our experiments is similar to what you want to do, just press the button and change it to your needs.
Main tab
At the top, you see different tabs. 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 translations 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.
There is also another box in the "main" tab named "Analysis options". These determine how often phyphox should analyze your data. By default phyphox 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 phyphox 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 through 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.
Input/Output tab
Next stop: The "input" tab. Here you can define any source of data that goes into phyphox. At the moment of this recording, these are "audio", which is the microphone, "sensor", which is any of the phone's sensors like the accelerometer or the gyroscope and "bluetooth", which is a bluetooth device. You can of course add more than one input. Each type of input has different settings, which again are explained if you hover your cursor above the question marks.
The output tab is very similar, only this time you define any device to which phyphox should send data. Currently, there is only "audio", which is the phone's speaker and again "bluetooth". So, at the moment, unless you want to make a noise through the speaker, you probably won't add any output to your experiment.
Views tab
In the next tab, called "views", you can design the interface for your users. The phyphox interface consists of different elements, which are placed in different views. In the actual app, a view is shown as a tab. For example, the roll experiment has two views, one is called "velocity" and the other 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 roll's radius and two graphs giving the speed over time in m/s and km/h.
Currently, there are four different types of elements. "Info" just displays simple text to the user. Value shows a single value - if it is 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 your calculations like the roll's radius. Each element has individual settings, which once again, you can explore by hovering over the question marks or learn about them in the fileformat documentation.
Analysis tab
Now we get to the tricky part, where the inputs, outputs and the views are connected with some math inbetween in the "analysis" tab. You will notice, that all the elements you have added before are already here. So, any input, output or view from the previous tabs shows up in this tab and can be connected. Also, you may add even more modules as mathematical operations on the data. If you click on the name, they will expand, so you can change their settings here.
You will also notice, that most view elements have plus signs at the top of them. This is where you can put data into them. In contrast, you cannot put data into input modules, which is why they do not have these plus signs. Instead, they have lines to their right because you can get data from them. Each line is an output, if they are grey, they are not used. To use an output, you have to attach a buffer. To do so, click on the grey line, then click create and the line turns orange.
If you click the line again, you 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 tricky 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 this length, the first value is removed when a new number is added at 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 for your calculations. For a simple experiment without heavy calculations, there is 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 tick it if the values in a buffer never have to be calculated a second time, so phyphox can save some ressources there. For example static makes sense if the values are purely calculated from constants and not from sensor data or user input.
When you click on the plus sign of a module, you can choose the data source. For example, a buffer. The alternative, "value", would allow you to enter a single constant number. If you choose to connect a buffer, you can click on the button with three points below and then click on the buffer (i.e. horiizontal orange line) you want to use. The button now shows the buffer's name and you can confirm your choice with ok. Now, you can see that the buffer is connected to the graph.
If you want to add math, use the insert button between the existing elements to add analysis modules. Once again, there are many modules and options, so if you are looking for a specific mathematical operation, have a look at the fileformat documentation in this 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 most analysis modules have the plus buttons as well as the lines to the right. Obviously, you put data in and get a result. 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, phyphox will always keep adding data to the buffers, just like you expect it from a sensor. As an example, you do your calculation on the first five values from a sensor and append them to a buffer going to a graph. The calculations are done and phyphox 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, phyphox will calculate the data again for the first five values and then for the five new values and appending them all to the buffer going to 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 you want!
So, there are two options: Option 1 is enabling "clear" on the input, so the sensor buffer is cleared when reading it as a source for the analysis. 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 sometimes you still need the data for the another graph or more calculations. You could copy the data into a different buffer first, but there is a better solution.
In many cases, when the mathematical operations are not too heavy, you can just clear the buffer to which you write the results of your analysis. The drawback is, that phyphox will recalculate all the data each time, but that is ok if the calculation is not such a heavy task. So in the simple example, the buffer going to the graph will always contain fresh values corresponding to the values in the sensor buffer and, also quite important, the time buffer from the same sensor.
Export tab
There is one more tab, which you 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 phyphox, which data is relevant. The export is structured into different set. You can think of each set as a collection of data that can be presented in a single table. 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 that Excel file.
XML tab
The last tab just shows us the source of the generated phyphox file, which may be helpful to learn XML or check for errors, but otherwise you can ignore it.
