Remote-interface communication

While the remote interface of phyphox is a very powerful tool, you might be interested in communicating and controlling phyphox directly using your own software. The web page called by your browser when using the default remote interface is mostly based on some (not too complex) Javascript code. This code does a range of AJAX requests and receives responses in a JSON format, which are documented on this page.

In principle, with this information, you could embed phyphox into many other projects. For example, you could write an interface to perform measurements including more than one phones with phyphox or you could include phyphox into a more capable measurement software (LabView, Labber, Matlab) or control phyphox alongside other lab equipment like programmable voltage sources or power supplies of electro magnets.

As the interface is designed around a webserver running on the phone, all functions are available as documents below the devices URL. So, this documentation will list all these documents from the document root. For example "/get" can be called as http://192.168.0.42:8080/get (if the phone's IP is 192.168.0.42 and the server is running on port 8080. On iPhones, the server runs in port 80, so for http the port can usually be omitted.)

Documents

/, /style.css and /logo

These documents are not relevant for controlling phyphox with your own code. They make up the webpage that is the default remote interface. The document root itself serves an html file with the Javascript of the interface, while style.css and logo serve the Style Sheet and an image file of the phyphox logo.

/get

A call to get retrieves the measured data as well as the current status of phyphox. The response is a JSON object of the following form:

{"buffer": {...}, "status": {...}}

Both, "buffer" and "status" again are JSON objects, containing buffer data and the app status respectively. The contents of "buffer" depend on the buffer that you request as parameters to /get. For example, you can request the buffers "abc" and "def" using the request "/get?abc&def". This request, however, will only return the last value in each buffer. To receive more values, you have to specify to either retrieve the full buffer or all values beyond a certain threshold: "/get?abc=full&def=42" will return all values of buffer "abc", but only the remaining values from buffer "def" after the first value exceeding 42.

Retrieving the full buffer is straight forward, but can be quite inefficient. Instead using the threshold can save a lot of bandwidth if you only need to retrieve new data from a monotonic reference. A typical example is a time axis - you have already received data from a sensor every second as pairs of (time|value): (1,7), (2,-1), (3,4) As you know, that "time" will always increase monotonic. So from buffer "time", you only need to request anything after the value 3: "/get?t=3". Buffer "value" is slightly more complicated as it might have any value, but you know that you only need those values at the same index as the values of "time" larger than 3. So, when giving a threshold to a buffer in the get-request, you can add a specific reference buffer: "/get?time=3&value=3|time". If the threshold value does not belong to the requested buffer itself, you have to provide it after the threshold with the symbol "|".

This is necessary as values are not explicitly paired in phyphox experiment. It may be absolutely valid, that you need a subset from the "time" buffer, and the full "value" buffer, which might be unrelated. So, a last example:

/get?abc&def=full&ghi=42&jkl=23|mno

This request will return the last value of "abc", all values from "def", the values from "ghi" occuring after the first value above 42 and all values from "jkl" ocurring after the first index at which the value in buffer "mno" is larger than 23. Note, that "mno" itself is not requested.

The "buffer" JSON object in the response looks like this:

"buffer": {
  "abc":{"size":100, "updateMode":"partial", "buffer":[1,2,3.456E1]},
  "def":{"size":20, "updateMode":"single", "buffer":[1.222E-2]}
}

This response contains data for the buffers "abc" and "def". The "size" gives the total capacity of the buffer - not the number of values returned and not how much it is filled. "updateMode" can be "full", "partial" or "single", in which case you know that you have retrieved the whole buffer, a part of it or only its last value. "buffer" finally contains an array of the values returned.

The "status" JSON object contains four values:

"status": {
  "session":"abcdef", "measuring": true, "tiemdRun": true, "countDown":2.7
}

"session" gives a string identifier which is unique per session. If this changes, you may expect that the user has switched to a different experiment and all your old data has become invalid. "measuring" gives the current state of the measurement - false means that the experiment is paused, true that it is running. "timedRun" and "countDown" represent the timed run function. In this case it is enabled and will stop the current measurement in 2.7 seconds. If "measuring" was false, it would mean that the measurement would start in 2.7 seconds.

/control

The document "control" is used to send commands to phyphox to start and stop the experiment. It will always respond with a simple confirmation object {"result": true} if successfull or {"result": false} if something went wrong.

Currently, there are four commands available:

/control?cmd=start starts the experiment (or the countdown if timed run is enabled)

/control?cmd=stop stops the experiment

/control?cmd=clear clears all buffer (and stops the experiment if running)

/control?cmd=set&buffer=abc&value=42 Writes the value 42 into the buffer abc (typically used for edit fields)

/export

When requesting "export", you are effectively triggering the export function of phyphox to retrieve all recorded data in a single file. You can specify the format of this file using the index of the available formats. For example /export?format=0 will give a CSV file and /export?format=2 will give an Excel file (at the time of this writing).

Problems and future changes

A design flaw for external use is that the experiment setup with the used buffer names and the list of available export formats is currently written into the HTML file provided with the root document. This way, it is hard to parse this information. In a future version this will probably be made available through a JSON interface. If you need this functionality, please send us an email, so we know that it should move up in our priority list.