Commit f827b856 authored by Mark Wijzenbroek's avatar Mark Wijzenbroek
Browse files

Update docs

parent 3fc2902e
......@@ -2,4 +2,6 @@
The firmware can be compiled with a "standard" CodeSourcery ARM EABI toolchain. Note, this package is unfortunately no longer available through the website of the company who provided this. Luckily, the files are still available on their server. Check https://elinux.org/ARMCompilers for download links; the direct download link to the 2014 CodeSourcery stack is available at https://sourcery.mentor.com/GNUToolchain/package12774/public/arm-none-eabi/arm-2014.05-28-arm-none-eabi-i686-pc-linux-gnu.tar.bz2
Please note the copyright for the firmware lies with Salland Electronics, it cannot be freely distributed.
Adapt Makefile.posix to the place where you unpackaged the ARM toolchain. In principle you should be able to use another ARM EABI toolchain, BUT note that these other toolchains do not have libcs3*.a, which is the CodeSourcery loader, on which the firmware relies.
How to: a practical guide
===
This document describes a high level description of how the whole system is used.
The different hardware components are described [here](whatswhat.md).
## Step 1: prepare the proximity sensors
You will need to create at least one checkin and checkout node per "badge station", but it might be a good idea to have some spares as well in case of problems. Checkin nodes activate the other badges, checkout nodes deactivate the others. You may want to use "anchors" as well, which are regular nodes that you place somewhere in space.
After you have determined how many sensors you want to use, you need to flash the firmware on the sensors with the software in the flash folder. For more details on how to connect the sensors to the computer, see the [What's what](whatswhat.md) document. Do not forget to put a battery in the development board and the node you are flashing (can be removed again once the flashing is completed). After flashing, check whether the pattern the flashing LEDs make is consistent with what you are expecting ([see here](whatswhat.md)).
For more details on how to use the wrapper script, see [the readme file](../flash/README.md). Usually using the firmware as indicated by the types is sensible. For the regular badge nodes and the anchors, we recommend using the 2018 firmware (type: node, file: km_node_2018.hex). The anchor firmware is older and there is little sense in using it. It is recommended to store the
## Step 2: prepare and hand out badges
After you've prepared the proximity sensors, you can make your "badges". Usually you put them in a (non conducting) plastic bag together with a piece of paper (e.g. instructions, experiment name, and so on) attached to a lanyard. If you want a non-anonymous experiment, make sure you have the badge ID number (probably equal to the ID number of the proximity sensor) visible on the outside of your badge, so that you can write a name (or participant type) in an Excel sheet or similar. Make sure you have some spare badges on hand for late arrivals and so on.
You will need to prepare at least one "badge station" where you can hand out and receive badges. Prepare an easy way to checkin and checkout badges (keep these nodes well separate and marked to prevent interference and mistakes!). Badges need to be checked in to start recording data, and do not stop until they are checked out again. After checkout, they first need to be downloaded before they can be checked in again!
Once a new participant arrives, check in a badge and hand it out. Register any extra information you need for your experiment based on the ID number.
## Step 3: collect the badges and download the data
When the experiment is over, check out the badge and - if preferred and possible - begin the download. Please note - keep the download node several meters away from your badges to avoid interference! The download node is rather sensitive and will probably (try to) download well before you expect it to. It does on occasion happen that two nodes will try to download at the same time, causing their results to be garbled together. As the nodes are immediately wiped after download, this should be avoided to prevent data loss! The downloader will output several files including the system log and the detection log in json format.
To avoid problems, we recommend first downloading only the raw logs (use the -J option of kumbhdownloader to prevent immediately making json files) and then separately process them (kumbhprocessor). This way, you can easily concatenate results from multiple dump files (e.g. if you have multiple badge stations or because something went wrong), but you can also manually edit the dumps to remove spurious interactions with the download node (i.e. incomplete downloads).
## Step 4: parse the system and detection logs
You will probably want to visualize the network in i.e. Gephi. To do that, we've created some Python scripts that convert the .json logs into a .gexf file. These scripts are located in the network_builder folder and should run under Python 2.7 or 3.x.
......@@ -33,13 +33,13 @@ Each proximity sensor has two LEDs (green and red). Depending on which firmware
Only the regular nodes register proximity data and can be checked in or out. Furthermore note that:
* The 2018 firmware registers every 6 seconds to the system log and the detection log;
* The final firmware from the Kumbh-Mela project registers every x seconds to the system log and every y seconds to the detection log.
* The (old) final firmware (source code included) from the Kumbh-Mela project registers every x seconds to the system log and every y seconds to the detection log.
# Checkpoints
The checkpoints were built by SallandElectronics and are connected to a computer with the USB to micro USB cable. The device acts as a serial device (ftdi chip). The ftdi_sio driver is used under Linux to connect, which may or may not be present on your system (CentOS 7 provides this driver out of the box). On newer kernels you may need to load this driver manually.
There are three types of checkpoints: download nodes, which when connected have a slowly flashing red LED, time synchronization nodes, which when connected have a quickly flashing orange LED, and sniffer nodes, which have a slowly flashing or continuously on orange LED. The download nodes are used to download data to your computer, whereas the time nodes are used to synchronize the time. The sniffer nodes can be used to investigate the network in real time.
There are three types of checkpoints: download nodes, which when connected have a slowly flashing red LED, time synchronization nodes, which when connected have a quickly flashing orange LED(? Don't think they are actually used in the final design.), and sniffer nodes, which have a slowly flashing or continuously on orange LED. The download nodes are used to download data to your computer, whereas the time nodes are used to synchronize the time. The sniffer nodes can be used to investigate the network in real time.
To activate the download node you should use the kumbhserial code that is also included in this repository. Offer the checked out nodes to the download node one after another, and make sure you are not too fast! The proximity sensor will have its green LED on while the download is in progress. After this, the sensor may blink its red LED for some time (erasing?). Do not offer a second proximity sensor to the download node before the first node has stopped blinking. Otherwise it may get confused and your data may be lost or muddled together as it wipes the data from the checked out node when you download. Also, make sure you keep only one proximity sensor close to the download node, otherwise it may attempt to start the download on both.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment