Welcome to the FVF Measurement System Documentation¶

Pieces¶

The FVF measurement system consists of multiple pieces:

• Tube
• Hardware LED controller (Arduino Uno)
• Client Software

Components¶

The software consists of multiple components written in multiple programming languages:

• Arduino Firmware (C++)
• LED Driver (Java)
• Client Software (Java)

Folders¶

The folders and what they contain in this repository:

• docs/ - contains the source files for this documentation
• driver/ - contains the source files for the Driver
• firmware/ - contains the sources files for the Firmware
• software/ - contains the sources files for the Software
• manual/ - contains the sources files for the manual

Available Commands¶

• on
• flicker
• off
• measurement
• ping

Detailed information about the input and output about the firmware is described in the LED Protocol.

References¶

• Arduino Website
• Arudino IDE
• Arduino API

Verification¶

To ensure the flickering frequency a verification measurement has been done with VOLTCRAFT Universal SYSTEM MS-9150 Frequency Counter.

An important Note: The delay() method on the Arduino passes the delay in integer values, no floats are possible. For every milliseconds below 16383, delayMicroseconds() must be used. The gap happens between 30Hz and 31Hz.

Results¶

Frequency	Measured Frequency	Offset
10Hz	9,996	-0,004
11Hz	11,105	+0,105
12Hz	12,186	+0,185
13Hz	13,146	+0,146
14Hz	14,270	+0,270
15Hz	15,071	+0,071
16Hz	16,110	+0,110
17Hz	17,220	+0,220
18Hz	18,488	+0,488
19Hz	19,200	+0,200
20Hz	19,966	-0,034
21Hz	21,567	+0,567
22Hz	22,678	+0,678
23Hz	23,756	+0,756
24Hz	24,935	+0,935
25Hz	24,941	-0,059
26Hz	26,245	+0,245
27Hz	27,704	+0,704
28Hz	29,191	+1,191
29Hz	29,196	+0,196
30Hz	31,138	+1,138
31Hz	30,772	-0,328
32Hz	31,723	-0,277
33Hz	32,712	-0,288
34Hz	33,702	-0,298
35Hz	34,689	-0,311
36Hz	35,673	-0,327
37Hz	36,657	-0,343
38Hz	37,646	-0,354
39Hz	38,633	-0,367
40Hz	39,621	-0,379
41Hz	40,598	-0,402
42Hz	41,590	-0,41
43Hz	42,578	-0,422
44Hz	43,562	-0,438
45Hz	44,544	-0,456
46Hz	45,275	-0,725
47Hz	46,520	-0,48
48Hz	47,500	-0,5
49Hz	48,481	-0,519
50Hz	49,465	-0,536
51Hz	50,454	-0,546
52Hz	51,436	-0,564
53Hz	52,414	-0,586
54Hz	53,152	-0,848
55Hz	54,389	-0,611
...
500Hz	468,991	-32,009

The next graph shows the scattering of the measured values around the expected linear ideal values.

Communication¶

The client software talks to the Arduino board through a serial port connection. For this purpose the RXTX interface is used. In order to check whether the connection is still established, the driver periodically sends a ping to the board. Once this connection is interrupted for several reasons, it’s assumed the connection is dead.

Protocol¶

The driver implements the LED Protocol.

Deployment¶

The driver is deployed as *.jar file into the softwares lib/ folder.

Note: This is not ideal and must be triggered manually. Better solutions are welcome.

Remarks¶

There is a rxtx wiki entry describing how to bundle the jni extension with an eclipse rcp application.

$ file librxtxSerial.jnilib
librxtxSerial.jnilib: Mach-O universal binary with 2 architectures
librxtxSerial.jnilib (for architecture ppc):  Mach-O dynamically linked shared library ppc
librxtxSerial.jnilib (for architecture i386): Mach-O dynamically linked shared library i386

$ file librxtxSerial.jnilib
librxtxSerial.jnilib: Mach-O universal binary with 4 architectures
librxtxSerial.jnilib (for architecture x86_64):       Mach-O 64-bit bundle x86_64
librxtxSerial.jnilib (for architecture i386): Mach-O bundle i386
librxtxSerial.jnilib (for architecture ppc7400):      Mach-O bundle ppc
librxtxSerial.jnilib (for architecture ppc64):        Mach-O 64-bit bundle ppc64

References¶

• RXTX
• Arduino Java Interface

Database¶

Database development is realized via sormula ORM. The models are placed in the de.tu_darmstadt.sport.fvf.model package. The respective ERM is available as appendix. It is a SQLite database which is realized with SQLJet and connected with SQLite JDBC.

Icons¶

Icons are Silk by famfamfam and Fugue by Yusuke Kamiyamane.

Installing Arduino¶

Installing the Arduino IDE is straight forward. From the Arduino Website download the Arduino IDE for your platform and open firmware/fvf/fvf.ino to start your firmware development.

Install Git¶

Git is used as VCS and GitHub as repository master.

Installing Eclipse¶

Eclipse is the main development environment. A good start is to download the Eclipse for RCP and RAP Developers package.

Required Plugins¶

Since this is an e3 Plug-In deployed in an e4 environment all required compatibility layer plugins must be added.

Export the RCP application¶

Open the fvf.product file in eclipse. On the Overview page there is the export section with a link to open the “Eclipse Product export wizard” (which is also available from the toolbar of this editor). Make sure to check “Export for multiple platforms” (which is only available if you followed the Install Deployment Tools instructions) and “Synchronize before exporting”. Click “Next” which shows the available platforms to deploy to.

Automated Builds¶

Currently deploying the software is a manual job. It would be more pleasant to have automated builds. This especially means two tasks:

1. Driver and FVF are two independent projects right now, which means deploying the driver first to use it from FVF, it would be way easier to just refer to the driver project instead.
2. Deploy the software (with all it’s required libs). Either automatically, by committing, tagging a release or trigger the build manually.

For option #2 (continuous deployment) there are some online services available, which must be checked individually if they are eligible for the task on hand:

• semaphore
• codeship
• dploy
• drone.io
• circleci

Additionally, there must be found a good place to distribute binaries to.

Streamline Web Presence¶

The current web presence is cluttered among this docs and the manual. A formal webpage introducing FVF, what it is, who is responsible for that, where to download, how to contribute and contains links to the docs and manual is missing. Probably GitHub pages are a solution to island this or possibly put this up on the IFS website.

Internationalization (i18n)¶

Right now, the docs are in english, software and manual are in german. All tools within the toolchain support internationalization. This can be used to better translate all occurring strings. Transifex is an online service to keep track of all translations, which can be used as a managing instance. There is even an integration between Transifex and Sphinx, to translate docs.

Self-Validation¶

A self-validation routine built into the Firmware that averages the deviation for each frequency and applies it during the measurement routine.

Post-Processing of Results¶

The results can receive some post-processing by either showing statistics and displaying graphs or providing exports to various formats for further processing, e.g. exporting to SPS.

Instructions to setup your own FVF measurement system¶

Instructions to setup one’s own FVF measurement system. With technical specifications of the tube and the oculus adapter to connecting the software. Likewise a step-by-step manual for a self-construction-kit.

Port to eclipse e4¶

For historical reasons, the software is built on eclipse e3 API. At the time of writing, e4 is the current API and contains modern programming approaches to simply development. It can be worth to port the codebase to the new e4 API.

Schema¶

The following schema is used for every command, in every direction:

cmd [arg1] [arg2] ... [argN]

Input¶

Commands send to the hardware

on [led]

flicker [led] [frequency] [duration] [[light]] [[dark]]

off [led]

measurement [mode] [flickerLed] [frequency] [onDuration] [offDuration]

ping [[seq]]

Output¶

Feedback received from the hardware.

on [led]

flicker [led]

off [led]

measurement [state]

ons [mode]

offs [mode]

pong [seq]

error [number]

Error Codes¶

Error code explanation:

• 0 - Unknown Error
• 1 - Malformed command
• 2 - Unknown command
• 3 - Too few arguments for flicker command

Troubleshooting¶

1. Getting a “Port in Use” exception on OSX, when connecting to the Arduino Board -> See here: https://marcosc.com/2011/10/arduino-java-error-serial-port-already-in-use/