Electromagnetic Field - User contributions [en]

TiLDA MKe

2015-03-06T21:01:14Z

Marekventur:

[[File:IMG_0474.jpg|500px|right|thumb|Front]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=EMF 2014 Badge=
The main aim of the 2014 badge is to give camp attendees an interesting bit of hardware to play with during the camp and experiment with afterwards. We designed an Arduino compatible platform to allow easy reuse and access, and have published all code and design files.

==Battery Warning==
A very last minute battery (and connector) change on the badge due to a supplier problem meant two issues arose with the badge during EMF:

* '''Always make sure to plug your battery in the right way round!''' The new battery connector allows you to connect it backwards. We did our best to mitigate this, but connecting it incorrectly will destroy the power management controller and prevent the badge from charging or running from the battery. It will still function perfectly using USB power. "Red" and "Black" are written next to the connector - please make sure to plug it in correctly.

* '''Be careful not to short the battery connector wires!''' The new battery connector slightly exposes the wires when the battery is plugged in. If a metal object shorts the two wires, it can result in extreme battery damage. If we'd known this was such an issue before the event we would have applied protective material to it - we suggest covering the exposed connector in tape, sugru, blu-tack, or some other insulating material. Alternatively, simply unplug the battery when your badge is not in use!

==My badge is broken!==
Due to the aforementioned supplier issues it is possible that you may have received a faulty badge, or it may have been damaged by connecting the battery backwards. If you badge will not turn on when it has been plugged in with a MicroUSB cable (and the power switch on the back is set to "USB"), or something else seems wrong with it, please email [mailto:badge@emfcamp.org badge@emfcamp.org] and we'll try to fix or replace your badge.

==Basic post-event features==
We made sure that the badge has a few features to play with once the event is over. More will be added over time as attendees submit changes to us.

[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris

But of course the point of the badge is to modify it and use it for other interesting things! The following sections describe how to update the firmware on the badge, how to use it as a simple arduino, and how to write your own code for the main badge firmware.

==Getting help==
The EMF 2014 badge is a complex piece of hardware and software, however remember that you can just treat it as an Arduino if you find it all too daunting.

If you get stuck and need advice, there's an [http://webchat.freenode.net/?channels=tilda active IRC chatroom] you can join to ask for advice, or if you're really stuck you can email us on [mailto:badge@emfcamp.org badge@emfcamp.org].

=How to update the badge software & program the badge=
The badge software has been substantially updated since EMF, fixing bugs and removing features that will no longer work now you're away from our radio network. You should update your badge before starting to play with it any further. If you've never used an Arduino before this might be tricky - ask an Arduino-literate friend to help you, or drop by your nearest [http://hackspace.org.uk hackspace] and ask for advice.

The badge is Arudino Due compatible, so [http://arduino.cc/en/Guide/ArduinoDue some of their instructions may help you if you have problems].

==Set up your environment==
* Plug your badge into your computer via a MicroUSB cable. Make sure the power switch on the back is set to "USB".
* Download the newest version of the Arduino IDE from http://arduino.cc/en/main/software
* Download the TiLDA firmware code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned or downloaded. To do this use File -> Preferences -> “Set Sketchbook location”. On MacOS, this is Arduino -> Preferences.
* Restart the Arduino IDE.
* Open sketch “EMF2014”.
* Set Tools -> Board to MKe v0.333 (RTOS Core).
* Set Tools -> Port to correct port for the Arduino
** On MacOS this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Your badge should now be running the latest TiLDA firmware!

==Programming the badge as an Arduino==
The badge is completely Arduino Due compatible, simply set the board type to "MKe v0.333(Arduino Core)" upload normal Arduino code and the badge will function. However if you want to use any of the more complex hardware on the badge (such as the screen and radio) we recommend programming it using our FreeRTOS framework documented below.

Below is a version of the standard blink sketch that will flash the RX and TX LEDs

<code>
void setup() {
pinMode(PIN_LED_TX, OUTPUT);
pinMode(PIN_LED_RX, OUTPUT);
}

void loop() {
digitalWrite(PIN_LED_TX, HIGH);
digitalWrite(PIN_LED_RX, LOW);
delay(1000);
digitalWrite(PIN_LED_TX, LOW);
digitalWrite(PIN_LED_RX, HIGH);
delay(1000);
}
</code>

If you do program the badge with simple Arduino code but wish to switch back to our official firmware, simply change the sketch to "EMF2014" (and if needed set the board type back to "MKe v0.333 (RTOS Core)") and upload again.

To make the badge Arduino shield compatible, follow [https://wiki.emfcamp.org/wiki/TiLDA_MKe#Making_the_badge_Arduino_shield_compatible these instructions].

===Gotchas===
* Most Arduino code out there use Serial not SerialUSB. On MKe Serial is wired to the SRF radio. When using example code do a find and replace for Serial/SerialUSB this will redirect the Serial traffic of the USB port
* If you want to send data over the Radio you need to wake it and enable it first, set SRF_SLEEP to LOW using the following two lines of code <code>pinMode(SRF_SLEEP, OUTPUT); digitalWrite(SRF_SLEEP, LOW);</code>

==Programming the badge in FreeRTOS==
===Your first “Hello world” app===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

If you are still using the Arduino IDE at this point, note that it will not let you edit the .cpp and .h files that are needed to create Apps for the badge. To force the IDE to re-compile/re-read any files you've edited using an external editor, make sure to go to the File -> Preferences dialog box, and check the "Use external editor" checkbox.

===Why are things so different from standard Arduino code?===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard Arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spent quite a lot of time to make the built-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headaches if you stick to those.

=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(

==Debugging and Gotchas==
* The USB serial is set up to 115200 baud. There are lots of terminals that can connect to them. See below for how to enable the debug logging.
* If you can’t revive a badge, or only get the two red programming LEDs when you plug it, in, do a full erase (see below)
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
* If sending code to the badge using the Arduino IDE "Upload" button fails, even though the /dev/ttyACM0 (linux com port) is there, just retry, twice if neccessary.

==Full erase==
This is the failsafe process if your badge won't show up over USB.

# Unplug the badge
# Connect the Erase pins on the back together (two holes down the left hand side next to the battery and under the blue wireless module). You can use a jumper, jump wire, or the leg of a resistor for this.
# Turn the badge back on with the switch or plug it back in
# Press the Reset button on the front (bottom centre) and release
# Wait 15 seconds
# Unplug the badge or turn it off

When you plug the badge back into a computer it will come back up in programming mode, with a different serial port to the usual one. Open the EMF 2014 sketch in the Arduino IDE, select the Tilda v0.333 (RTOS) programmer, and find the new serial port. The IDE console should show something like this:

Sketch uses 118,748 bytes (22%) of program storage space. Maximum is 524,288 bytes.
Erase flash
Write 127668 bytes to flash

[ ] 0% (0/499 pages)
[ ] 2% (10/499 pages)
[= ] 4% (20/499 pages)
[= ] 6% (30/499 pages)
...
[============================= ] 98% (490/499 pages)
[==============================] 100% (499/499 pages)
Verify 127668 bytes of flash

[ ] 0% (0/499 pages)
[ ] 2% (10/499 pages)
[= ] 4% (20/499 pages)
[= ] 6% (30/499 pages)
...
[============================= ] 98% (490/499 pages)
[==============================] 100% (499/499 pages)
Verify successful
Set boot flash true
CPU reset.

==Your own wireless badge network==
[[DIY TiLDA Badge Network]] has instructions on how to setup your own private badge network using a RaspberryPi and two Ciseco radios.

==Contribute==
Send us a pull request via [https://github.com/emfcamp/Mk2-Firmware GitHub] - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Using the badge hardware=
The badge has a plethora of hardware built in for you to play with, everything from accelerometers and gyroscopes to hidden ethernet headers! Breaking it all down is too much detail for this document, however we'll call out some things we built in that you might want to play with.

Remember the badge is Arduino Due compatible, and we broke out nearly all the features of the ARM chip so you can access them. [http://arduino.cc/en/Main/ArduinoBoardDue Anything the Due can do], the TiLDA can do!

==Making the badge Arduino shield compatible==
[[File:Sheild_Headers.JPG|500px|right|thumb|Sheild Headers]]
To make the badge Arduino shield compatible you'll need to solder simple strips of header pins onto the back of the badge.
You need the following headers
{| class="wikitable"
|-
! Qty !! Type !! Use !! Rapid part
|-
| 1 || 2x03 Male || SPI ||
|-
| 2 || 1x08 Female || Power, Analog pins ||
|-
| 2 || 1x10 Female || Digital pins ||
|-
| 1 || 2x08 Male || Ethernet ||
|}
The picture to the right shows the placement.

==Interesting things to play with==
Most of the interesting things are on the back of the badge. They're clearly marked in white. [https://wiki.emfcamp.org/w/images/b/bd/Badge_Back.png This diagram of the back] should allow you to locate them. Some of the following require extra parts to be added to your badge.

* Full Arduino R3 shield compatible pins (Requires soldering the headers on the back of the badge)
* Pins either side of the lanyard holes for conductive thread (D19, D18, GND, 3V3)
* Infrared transmitter on the front (Pin shortcut IR_TX_PWM)
* Infrared receiver on the front (Pin shortcut IR_RX, Part Vishay TSOP75238TT available from digikey and Farnell )
* Piezo buzzer (Pin shortcut PIEZO or PIEZO_PWM)
* On-board ethernet (not available on the Due) - requires breakout module (eBay: Elechouse Taijiuino Ethernet PHY DM9161 Module)
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro (IMUTask.cpp and the MPU6050 library)
* 128x64 pixel backlit LCD display (JHD12864, see [https://github.com/emfcamp/Mk2-Documentation/tree/master/LCD%20JHD12864 here for docs])
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
* [http://shop.ciseco.co.uk/powerpod-ncp1402-5v0/ PowerPOD NCP1402] interface, used to generate 5V from 3V3 battery supply power (needed for some shields)
* MicroSD adapter breakout (Molex 1050270001 available from digikey)
* Compass (magnetometer) breakout (HMC HMC5883L-TR available from digikey and Farnell)
* Reprogramming headers for the 868Mhz [http://www.ti.com/product/cc1110f32 CC1110 radio module]
* 1 megabit flash module (Part S25FL216K0PMFI011)
* SPI breakout
* 2x RGB LEDs on the front
* FTDI header (shared with SRF Radio)
* JTAG header (Part M50-3500542 available form Farnell

==Included hardware==

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronisation and gesture detection
* PMIC & LiPo
* Joystick, 4 way with click
* Buttons
* RGB LEDs
* IR Transmitter
* Arduino Headers
* Pads for wearable tech

=Useful Hacks!=
==3d printable & laser-cuttable badge case==
Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]
==Convert images to TiLDA bitmap format==
* A Python script (via [https://twitter.com/trotmaster99 @trotmaster99]) that converts a monochrome bitmap image into a format suitable for the Tilda can be found [http://pastebin.com/8XeazQjT here].
* A similar script in Perl to create TiLDA MKe fullscreen bitmaps from XBM: -
<div style ="height:200px;overflow-x:hidden;overflow-y:auto;border: 4px solid orange;">
'''xbm2mke.pl by [[User:Msemtd]]'''
<nowiki>
#!perl -w
use strict;
# Little script to convert a regular XBM to TiLDA MKe bitmap
# only tested with fullscreen bitmaps!
# Hot file handle magic...
select((select(STDERR), $| = 1)[0]);
select((select(STDOUT), $| = 1)[0]);
sub t(@);
sub d($);
sub chug($);
my $f = shift;
#~ $f = 'blankish.xbm' if not $f;
if(not defined $f or not $f =~ /^(.*)\.xbm$/i){
die "Usage: gimme an XBM file dude!\n";
}
my $name = $1;
t "Reading file '$f'...";
my $data = chug($f);
t "OK";
my @lines = split /^/, $data;
@lines = grep{chomp; s/^\s+//; s/\s+$//; length;} @lines;
#~ t d \@lines;
my($width, $height) = (0,0);
my @head = @lines[0..5];
foreach(@head){
if(/_width\s+(\d+)/){$width = $1;}
if(/_height\s+(\d+)/){$height = $1;}
}
t "width x height = $width x $height";
my @k;
foreach(@lines){ push @k, split /,/; }
@k = grep { s/^.*(0x[0-9A-Fa-f]{1,2}).*$/$1/o; /(0x[0-9A-Fa-f]{1,2})/o } @k;
#~ t d \@k;
my $bc = scalar(@k);
t "Pulled out $bc hex bytes";
if($bc != $width * $height / 8) {
die "byte count $bc does not match that expected for w x h";
}
t "OK - reorder bytes for MKe bitmap";
my $wb = int($width/8) + (($width & 0x07) ? 1: 0);
t "width in whole bytes for $width pixels = $wb";
my @mke;
for(my $col = 0; $col < $wb; $col++){
for(my $row = $height - 1; $row >= 0; $row--){
my $idx = ($row * $wb) + $col;
my $val = $k[$idx];
#~ t "Column $col + Row $row = idx $idx = $val";
push @mke, $val;
}
}
my $out = "static const uint8_t ".uc($name)."_BM[] = {\n"
." $width, // width\n"
." $height , // height\n";
#~ $out .= join(", ", @mke);
while(scalar @mke){
$out .= join(", ", splice(@mke, 0, 16)).",\n";
}
$out .= "};\n";
# meh, just print it out
t $out;

sub t(@) {
foreach (@_) {
print STDOUT "$_\n";
}
}
sub d($) {
require Data::Dumper;
my $s = $_[0];
my $d = Data::Dumper::Dumper($s);
$d =~ s/^\$VAR1 =\s*//;
$d =~ s/;$//;
chomp $d;
return $d;
}
sub chug($) {
my $filename = shift;
local *F;
open F, "< $filename" or die "Couldn't open `$filename': $!";
local $/ = undef;
return <F>;
} # F automatically closed

</nowiki>
</div>

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

If you want to help, point your IRC client to #tilda on Freenode.

= Firmware Documentation =
== Debugging ==
===Enabling the USB serial debug log messages===
To enable the debug logging you must uncomment the following line in [https://github.com/emfcamp/Mk2-Firmware/blob/master/hardware/emfcamp/sam/libraries/debug/debug.h#L42 hardware/emfcamp/sam/libraries/debug/debug.h]

// Enable debug task and output
// #define DEBUG 1

===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.

===Debugging using the JTAG interface===
The JTAG interface on the board provides powerful debugging facilities like breakpoints, backtraces, dumping memory, inspecting variables, checking task states, catching exeptions etc. To make this to work requires additional hardware and software, see [[TiLDA Debugging using JTAG]].

== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108), docs (http://code.google.com/p/glcd-arduino/source/browse/trunk/glcd/doc/GLCD_Documentation.pdf) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask. The bitmap format, by the way, is rather unconventional but there are a couple of utility scripts to convert popular formats down in the hacking section below - you can grab the SponsorsApp.h as an example and swap out the bitmap array with one of your choosing.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

Note that one function was not ported to the badge version of GLCD, "Printf", you'll have to cope without it.

== Sound ==
There's a fully working Piezo on board!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

== Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
There's no way of sending messages in the current version of the firmware, sorry :(

== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

[[Category: Badges]]

TiLDA Debugging using JTAG

2014-10-01T23:42:38Z

Marekventur: /* Running GDB */

The TiLDA badge has a JTAG port which can be used to perform remote firmware debugging. With the right hardware and software you can use this to run a GDB session on your development machine to insert breakpoints, inspect memory and poke around with the firmware running on the badge just like it was a local process running on your machine.

== Prerequisites ==
''I started the list below with the parts that worked for me. Feel free to add alternatives if you know they work for you.''
* X86-64 Linux machine for building the firmware and running GDB
* TiLDA badge
** Plus micro USB cable for connecting TiLDA to development machine
* JTAG header, 10 way (2 x 5 pins) 0.05" (or 1.27mm) through hole
** e.g. Samtec FTS-105-01-L-D
** or Harwin M50-3500542 (part number from the TiLDA schematic)
* Fine tipped soldering iron
* [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex ARM-USB-TINY-H] USB JTAG Interface
** Plus USB type A to B cable (the original & large square plug)
* [https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/ Olimex ARM-JTAG-20-10] 20pin to 10pin adapter
* [http://openocd.sourceforge.net/ OpenOCD] software.
** This can control the Olimex JTAG interface and implements the GDB remote server protocol to talk with the debugger
* GDB
** I used gdb-7.7.1-18.fc20.x86_64.
* Arduino 1.5.7 tools
** For building & installing the firmware image

== Attach JTAG Header to badge ==
The header must be attached on the correct side of the board otherwise it won't work. The pins on the two sides of the header are slightly different, one side is tin coated and appears silver/grey. These are the ones you should be soldering. The gold plated side should to be used by the connector.

[[File:jtag-header.jpg|150px|thumb|center|text-top|JTAG header before being soldered on to the board]]
[[File:jtag-header-in-place-highlight.jpg|300px|thumb|center|text-top|TiLDA with new JTAG header highlighted]]

Flip the board upside down and solder pins from the LCD side. The pitch is only 1.27mm (0.05") which is half the size of most normal connectors so you need a steady hand. After you have soldered the pins it is a good idea to test for any short circuits before you power it on.

[[File:jtag-header-solder-side.jpg|200px|thumb|center|text-top|Header soldered on LCD side of the board]]

== Olimex adapter and USB-TINY-H ==
The cable from the Olimex adaper should be connected to the header so that the cable runs away from the board. Once again you may wish to check the connections appear to be the right way around, e.g. pin 1 on the adapter board connects to the 3v3 test point on the TiLDA. Connect the 20 pin side of the adapter into the main USB-TINY, this is keyed so it only fits one way around.

[[File:board-with-adapter.jpg|300px|thumb|center|text-top|TiLDA connected to Olimex TINY-Y]]

Plug the USB-TINY into a USB port on your machine. The 'dmesg' output should report something like:

usb 2-2: new high-speed USB device number 111 using ehci-pci
usb 2-2: New USB device found, idVendor=15ba, idProduct=002a
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: Olimex OpenOCD JTAG ARM-USB-TINY-H
usb 2-2: SerialNumber: OLXxxxxx

== Atmel ICE Basic ==
If you use an Atmel ICE then the cable needs to be connected so that it runs over the top of the board. The red stripe indicates pin 1.
[[File:CIMG1383.JPG|300pix|thumb|center|text-top|TiLDA connected to Atmel ICE Basic]]
<nowiki>
[jburgess@shark openocd]$ sudo openocd -f interface/cmsis-dap.cfg -f target/at91sam3XXX.cfg
Open On-Chip Debugger 0.9.0-dev-00161-g9c47dc9-dirty (2014-09-30-23:42)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'cmsis-dap'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
cortex_m reset_config sysresetreq
Info : CMSIS-DAP: SWD Supported
Info : CMSIS-DAP: JTAG Supported
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : CMSIS-DAP: FW Version = 01.00.0021
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 0 nTRST = 0 nRESET = 1
Info : DAP_SWJ Sequence (reset: 50+ '1' followed by 0)
Info : CMSIS-DAP: Interface ready
Info : clock speed 500 kHz
Info : IDCODE 0x2ba01477
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>

== Install OpenOCD ==
I started with the current version available in the Fedora package repository (openocd-0.7.0-3.fc20.x86_64). Other Linux distros are likely to have packaged too.

=== OpenOCD stack pointer bug ===
After I got everything running I noticed that the GDB backtraces would show the current function (PC) and the caller (LR) but all further stack entries were missing. After some debugging I found that OpenOCD was incorrectly calculating the stack pointer when it tried to align it. I applied a quick fix to disable the broken alignment code:

<nowiki>
--- openocd-0.7.0/src/rtos/rtos.c.bak 2014-09-14 17:28:10.000000000 +0100
+++ openocd-0.7.0/src/rtos/rtos.c 2014-09-14 17:29:39.000000000 +0100
@@ -454,12 +454,16 @@
tmp_str_ptr = *hex_reg_list;
new_stack_ptr = stack_ptr - stacking->stack_growth_direction *
stacking->stack_registers_size;
+#if 0
+ // This code gives bad results for already aligned pointers
+ // and negative stack growth
if (stacking->stack_alignment != 0) {
/* Align new stack pointer to x byte boundary */
new_stack_ptr =
(new_stack_ptr & (~((int64_t) stacking->stack_alignment - 1))) +
((stacking->stack_growth_direction == -1) ? stacking->stack_alignment : 0);
}
+#endif
for (i = 0; i < stacking->num_output_registers; i++) {
int j;
for (j = 0; j < stacking->register_offsets[i].width_bits/8; j++) {
</nowiki>

I reported the bug to the OpenOCD developers and proper fix will hopefully arrive in the trunk code soon: http://openocd.zylin.com/#/c/2301/ (an initial fix was committed but has since been reverted because it was broken for a different case).

====Alternative (Debian/Ubuntu) ====

To do this you can download the code from http://sourceforge.net/projects/openocd/files/openocd/0.8.0/ and apply this patch http://openocd.zylin.com/#/c/2301/3/src/rtos/rtos.c,cm .

<nowiki>
sudo apt-get install libusb-dev libusb-1.0-0-dev
./configure --enable-armjtagew
make
sudo make install
./configure
</nowiki>

== OpenOCD configuration file ==
OpenOCD requires a set of configuration commands describing both the JTAG adapter and the target CPU/board. Copy this into a file called tilda.cfg:

<nowiki>
# Recommended for OpenOCD-0.7
# script interface/olimex-arm-usb-tiny-h.cfg

# Recommended for OpenOCD-0.8
script interface/ftdi/olimex-arm-usb-tiny-h.cfg

# script for ATMEL sam3, a CORTEX-M3 chip
script target/at91sam3XXX.cfg

$_TARGETNAME configure -rtos FreeRTOS
</nowiki>

=== Run OpenOCD ===
OpenOCD uses libusb to access the device and may need to run with sudo for it to work. If everything is connected together and the badge is powered on then you should see it detecting the CPU core as shown below:

<nowiki>
$ sudo openocd -f tilda.cfg
Open On-Chip Debugger 0.8.0 (2014-09-17-20:52)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m reset_config sysresetreq
Info : clock speed 500 kHz
Info : JTAG tap: sam3.cpu tap/device found: 0x4ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x4)
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>

=== CMSIS DAP ===
If you us an an CMSIS DAP compliant adapter such as the [[http://uk.farnell.com/atmel/atatmel-ice-basic/debugger-atmel-arm-avr-basic-kit/dp/2407172 Atmel ICE]] then OpenOCD can be run with <code>interface/cmsis-dap.cfg</code> e.g.

<nowiki>
$ sudo openocd -f interface/cmsis-dap.cfg -f target/at91sam3XXX.cfg
Open On-Chip Debugger 0.9.0-dev-00161-g9c47dc9-dirty (2014-09-30-23:42)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'cmsis-dap'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
cortex_m reset_config sysresetreq
Info : CMSIS-DAP: SWD Supported
Info : CMSIS-DAP: JTAG Supported
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : CMSIS-DAP: FW Version = 01.00.0021
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 0 nTRST = 0 nRESET = 1
Info : DAP_SWJ Sequence (reset: 50+ '1' followed by 0)
Info : CMSIS-DAP: Interface ready
Info : clock speed 500 kHz
Info : IDCODE 0x2ba01477
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>
This seems to be a little slower at single-stepping the code than the Olimex adapter but is a little cheaper and in theory provides a more flexible debug interface (SWD).

== Patch TiLDA firmware for OpenOCD FreeRTOS detection ==
The OpenOCD code knows how to find the FreeRTOS tasks and can use this to make each task running on the badge as a different thread in GDB. To make this work you need to apply a small patch to the TiLDA code.

<nowiki>
diff --git a/EMF2014/TiLDATask.cpp b/EMF2014/TiLDATask.cpp
index 2cdc08d..701f940 100644
--- a/EMF2014/TiLDATask.cpp
+++ b/EMF2014/TiLDATask.cpp
@@ -58,6 +58,8 @@
#include "logo.h"
#include "TiLDA_64x128.h"

+// Hack to make FreeRTOS support work in OpenOCD
+unsigned portBASE_TYPE uxTopUsedPriority;

TiLDATask::TiLDATask() {

@@ -68,6 +70,10 @@ String TiLDATask::getName() const {
}

void TiLDATask::task() {
+
+ // Hack to make FreeRTOS support work in OpenOCD
+ uxTopUsedPriority = configMAX_PRIORITIES - 1;
+
Tilda::_realTimeClock = new RTC_clock(RC);
Tilda::_appManager = new AppManager;
</nowiki>

This adds a variable that the OpenOCD expects to be able to read from the target to determine how many queues are being used by the FreeRTOS scheduler. This was present in older FreeRTOS release but has since been removed.

== Build and flash the badge firmware ==
To make the debugger work you must be sure that the firmware running on the badge exactly matches the source code and binary objects that you have locally on your development machine. I recommend you apply the patch from the previous section, build the TiLDA firmware and upload it to your badge before you go any further.

In the Arduino IDE you should build firmware (EMF2014 sketch) and upload it via the USB port on the TiLDA badge. (I have not attempted to upload firmware via the JTAG interface but that should be possible as well). The IDE writes a copy of the object files and the final executable to a directory in /tmp whenever you build the code. The firmware image file is <code>EMF2014.cpp.elf</code> and you want to find the most recently built one, e.g.

[jburgess@shark]$ ls -lt /tmp/build*/EMF2014.cpp.elf | head -n 1
-rwxrwxr-x. 1 jburgess jburgess 1475463 Sep 14 22:53 /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf

== Running GDB ==
First locate the EMF2014.cpp.elf file mentioned in the previous section. Run gdb with this file and with any luck it should be able to load it:

<nowiki>
[jburgess@shark tmp]$ gdb /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf
GNU gdb (GDB) Fedora 7.7.1-18.fc20
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-redhat-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf...done.
(gdb)
</nowiki>

=== Check debug symbols ===
Next try some simple commands to see whether GDB knows where symbols are located in the binary and source:

<nowiki>
(gdb) info line main
Line 43 of "/home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/cores/rtos/main.cpp" starts at address 0x8fe78 <main()> and ends at 0x8fe7a <main()+2>.
(gdb) list main
38
39 /*
40 * \brief Main entry point of Arduino application
41 */
42 int main( void )
43 {
44 init();
45
46 initVariant();
47
</nowiki>

If something goes wrong at this point you could try using the copy of GDB provided with the arduino tools instead, e.g. <code>arduino-1.5.7/hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb</code>

=== Attach GDB to OpenOCD ===
The OpenOCD supports a couple of different interfaces. Before we try GDB we should first stop the CPU using the basic control interface and tell it to halt the CPU:

<nowiki>
$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> halt
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0x000870ba psp: 0x20074a30
>
</nowiki>

To continue execution you can run "resume". Make sure you run "halt" to leave the target in the stopped before attaching GDB. Normally when GDB attaches it should stop the target automatically but this isn't working at the moment. If the target is running then you may when GDB attaches then you may see some odd behaviour.

The OpenOCD software runs a target server on localhost:3333 which we can ask GDB to attach to:
<nowiki>
(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
0x000870ba in prvCheckTasksWaitingTermination () at /home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
2839 while( uxTasksDeleted > ( UBaseType_t ) 0U )
(gdb)
</nowiki>

If you get "warning: Architecture rejected target-supplied description" try using "hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb" from Arduino's folder instead of whatever gdb you're distro has installed.

=== List FreeRTOS tasks ===
To list the running tasks you can use "info threads".

<nowiki>
(gdb) info threads
[New Thread 537348080]
[New Thread 537396632]
[New Thread 537402416]
[New Thread 537394216]
[New Thread 537405232]
[New Thread 537393096]
[New Thread 537348848]
[New Thread 537398824]
[New Thread 537400224]
[New Thread 537346984]
[New Thread 537403512]
[New Thread 537397728]
[New Thread 537395312]
Id Target Id Frame
14 Thread 537395312 (MessageCh) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
13 Thread 537397728 (RadioTran) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
12 Thread 537403512 (IMUTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
11 Thread 537346984 (TiLDATask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
10 Thread 537400224 (GUI) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
9 Thread 537398824 (LCD) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
8 Thread 537348848 (Tmr Svc) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
7 Thread 537393096 (RGBTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
6 Thread 537405232 (HomeScree) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
5 Thread 537394216 (BatterySa) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
4 Thread 537402416 (PMICTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
3 Thread 537396632 (RadioRece) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
2 Thread 537348080 (IDLE : : Running) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
* 1 Thread 537401320 (AppOpener) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
</nowiki>
Most threads should claim to be in "vPortYield()" which is one of the OS routines that a task will call when it wants to sleep for a while.Select a task and you can obtain its backtrace:
<nowiki>
(gdb) thread 6
[Switching to thread 6 (Thread 537405232)]
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
385 __asm volatile( "isb" );
(gdb) bt
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
#1 0x00085c60 in xEventGroupWaitBits (xEventGroup=0x20082b78, uxBitsToWaitFor=1, xClearOnExit=0, xWaitForAllBits=0, xTicksToWait=<optimized out>)
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/event_groups.c:357
#2 0x0008453e in HomeScreenApp::task (this=0x20082710) at /tmp/build9091009552223609902.tmp/HomeScreenApp.cpp:157
#3 0x000818b4 in Task::taskCaller (this=0x20082710) at /tmp/build9091009552223609902.tmp/Task.cpp:78
#4 0x00081906 in Task::_task (self=<optimized out>) at /tmp/build9091009552223609902.tmp/Task.cpp:87
#5 0x00086768 in ulPortSetInterruptMask () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:423
Backtrace stopped: previous frame identical to this frame (corrupt stack?)
</nowiki>

== Known issues ==
* <strike>Normally when you hit a breakpoint GDB will automatically switch to the thread that hit it. This is not happening at the moment. If you interrupt the code or hit a breakpoint you may have to manually switch threads. The 'info threads' puts "Running" next to task being executed and this is probably the one you need to switch to.</strike>
** Fixed by applying this patch to OpenOCD http://openocd.zylin.com/#/c/2303/
* When you attach and detach GDB doesn't automatically halt/resume the target. You can do this manually using the interface on port 3333 or just tell GDB to continue, then interrupt to stop it.
* GDB hits an assert if you detach the target and asks whether you want a core dump.
** This appears to be: https://sourceware.org/bugzilla/show_bug.cgi?id=12228
* I had a problem where the badge kept stopping at a breakpoint that I set in a previous GDB session and I was unable to fix it without power cycling the badge and restarting GDB & OpenOCD.

TiLDA Debugging using JTAG

2014-10-01T22:00:00Z

Marekventur: /* Install OpenOCD */

The TiLDA badge has a JTAG port which can be used to perform remote firmware debugging. With the right hardware and software you can use this to run a GDB session on your development machine to insert breakpoints, inspect memory and poke around with the firmware running on the badge just like it was a local process running on your machine.

== Prerequisites ==
''I started the list below with the parts that worked for me. Feel free to add alternatives if you know they work for you.''
* X86-64 Linux machine for building the firmware and running GDB
* TiLDA badge
** Plus micro USB cable for connecting TiLDA to development machine
* JTAG header, 10 way (2 x 5 pins) 0.05" (or 1.27mm) through hole
** e.g. Samtec FTS-105-01-L-D
** or Harwin M50-3500542 (part number from the TiLDA schematic)
* Fine tipped soldering iron
* [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex ARM-USB-TINY-H] USB JTAG Interface
** Plus USB type A to B cable (the original & large square plug)
* [https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/ Olimex ARM-JTAG-20-10] 20pin to 10pin adapter
* [http://openocd.sourceforge.net/ OpenOCD] software.
** This can control the Olimex JTAG interface and implements the GDB remote server protocol to talk with the debugger
* GDB
** I used gdb-7.7.1-18.fc20.x86_64.
* Arduino 1.5.7 tools
** For building & installing the firmware image

== Attach JTAG Header to badge ==
The header must be attached on the correct side of the board otherwise it won't work. The pins on the two sides of the header are slightly different, one side is tin coated and appears silver/grey. These are the ones you should be soldering. The gold plated side should to be used by the connector.

[[File:jtag-header.jpg|150px|thumb|center|text-top|JTAG header before being soldered on to the board]]
[[File:jtag-header-in-place-highlight.jpg|300px|thumb|center|text-top|TiLDA with new JTAG header highlighted]]

Flip the board upside down and solder pins from the LCD side. The pitch is only 1.27mm (0.05") which is half the size of most normal connectors so you need a steady hand. After you have soldered the pins it is a good idea to test for any short circuits before you power it on.

[[File:jtag-header-solder-side.jpg|200px|thumb|center|text-top|Header soldered on LCD side of the board]]

== Olimex adapter and USB-TINY-H ==
The cable from the Olimex adaper should be connected to the header so that the cable runs away from the board. Once again you may wish to check the connections appear to be the right way around, e.g. pin 1 on the adapter board connects to the 3v3 test point on the TiLDA. Connect the 20 pin side of the adapter into the main USB-TINY, this is keyed so it only fits one way around.

[[File:board-with-adapter.jpg|300px|thumb|center|text-top|TiLDA connected to Olimex TINY-Y]]

Plug the USB-TINY into a USB port on your machine. The 'dmesg' output should report something like:

usb 2-2: new high-speed USB device number 111 using ehci-pci
usb 2-2: New USB device found, idVendor=15ba, idProduct=002a
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: Olimex OpenOCD JTAG ARM-USB-TINY-H
usb 2-2: SerialNumber: OLXxxxxx

== Install OpenOCD ==
I started with the current version available in the Fedora package repository (openocd-0.7.0-3.fc20.x86_64). Other Linux distros are likely to have packaged too.

=== OpenOCD stack pointer bug ===
After I got everything running I noticed that the GDB backtraces would show the current function (PC) and the caller (LR) but all further stack entries were missing. After some debugging I found that OpenOCD was incorrectly calculating the stack pointer when it tried to align it. I applied a quick fix to disable the broken alignment code:

<nowiki>
--- openocd-0.7.0/src/rtos/rtos.c.bak 2014-09-14 17:28:10.000000000 +0100
+++ openocd-0.7.0/src/rtos/rtos.c 2014-09-14 17:29:39.000000000 +0100
@@ -454,12 +454,16 @@
tmp_str_ptr = *hex_reg_list;
new_stack_ptr = stack_ptr - stacking->stack_growth_direction *
stacking->stack_registers_size;
+#if 0
+ // This code gives bad results for already aligned pointers
+ // and negative stack growth
if (stacking->stack_alignment != 0) {
/* Align new stack pointer to x byte boundary */
new_stack_ptr =
(new_stack_ptr & (~((int64_t) stacking->stack_alignment - 1))) +
((stacking->stack_growth_direction == -1) ? stacking->stack_alignment : 0);
}
+#endif
for (i = 0; i < stacking->num_output_registers; i++) {
int j;
for (j = 0; j < stacking->register_offsets[i].width_bits/8; j++) {
</nowiki>

I reported the bug to the OpenOCD developers and proper fix will hopefully arrive in the trunk code soon: http://openocd.zylin.com/#/c/2301/ (an initial fix was committed but has since been reverted because it was broken for a different case).

====Alternative (Debian/Ubuntu) ====

To do this you can download the code from http://sourceforge.net/projects/openocd/files/openocd/0.8.0/ and apply this patch http://openocd.zylin.com/#/c/2301/3/src/rtos/rtos.c,cm .

<nowiki>
sudo apt-get install libusb-dev libusb-1.0-0-dev
./configure --enable-armjtagew
make
sudo make install
./configure
</nowiki>

== OpenOCD configuration file ==
OpenOCD requires a set of configuration commands describing both the JTAG adapter and the target CPU/board. Copy this into a file called tilda.cfg:

<nowiki>
# Recommended for OpenOCD-0.7
# script interface/olimex-arm-usb-tiny-h.cfg

# Recommended for OpenOCD-0.8
script interface/ftdi/olimex-arm-usb-tiny-h.cfg

# script for ATMEL sam3, a CORTEX-M3 chip
script target/at91sam3XXX.cfg

$_TARGETNAME configure -rtos FreeRTOS
</nowiki>

=== Run OpenOCD ===
OpenOCD uses libusb to access the device and may need to run with sudo for it to work. If everything is connected together and the badge is powered on then you should see it detecting the CPU core as shown below:

<nowiki>
$ sudo openocd -f tilda.cfg
Open On-Chip Debugger 0.8.0 (2014-09-17-20:52)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m reset_config sysresetreq
Info : clock speed 500 kHz
Info : JTAG tap: sam3.cpu tap/device found: 0x4ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x4)
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>

== Patch TiLDA firmware for OpenOCD FreeRTOS detection ==
The OpenOCD code knows how to find the FreeRTOS tasks and can use this to make each task running on the badge as a different thread in GDB. To make this work you need to apply a small patch to the TiLDA code.

<nowiki>
diff --git a/EMF2014/TiLDATask.cpp b/EMF2014/TiLDATask.cpp
index 2cdc08d..701f940 100644
--- a/EMF2014/TiLDATask.cpp
+++ b/EMF2014/TiLDATask.cpp
@@ -58,6 +58,8 @@
#include "logo.h"
#include "TiLDA_64x128.h"

+// Hack to make FreeRTOS support work in OpenOCD
+unsigned portBASE_TYPE uxTopUsedPriority;

TiLDATask::TiLDATask() {

@@ -68,6 +70,10 @@ String TiLDATask::getName() const {
}

void TiLDATask::task() {
+
+ // Hack to make FreeRTOS support work in OpenOCD
+ uxTopUsedPriority = configMAX_PRIORITIES - 1;
+
Tilda::_realTimeClock = new RTC_clock(RC);
Tilda::_appManager = new AppManager;
</nowiki>

This adds a variable that the OpenOCD expects to be able to read from the target to determine how many queues are being used by the FreeRTOS scheduler. This was present in older FreeRTOS release but has since been removed.

== Build and flash the badge firmware ==
To make the debugger work you must be sure that the firmware running on the badge exactly matches the source code and binary objects that you have locally on your development machine. I recommend you apply the patch from the previous section, build the TiLDA firmware and upload it to your badge before you go any further.

In the Arduino IDE you should build firmware (EMF2014 sketch) and upload it via the USB port on the TiLDA badge. (I have not attempted to upload firmware via the JTAG interface but that should be possible as well). The IDE writes a copy of the object files and the final executable to a directory in /tmp whenever you build the code. The firmware image file is <code>EMF2014.cpp.elf</code> and you want to find the most recently built one, e.g.

[jburgess@shark]$ ls -lt /tmp/build*/EMF2014.cpp.elf | head -n 1
-rwxrwxr-x. 1 jburgess jburgess 1475463 Sep 14 22:53 /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf

== Running GDB ==
First locate the EMF2014.cpp.elf file mentioned in the previous section. Run gdb with this file and with any luck it should be able to load it:

<nowiki>
[jburgess@shark tmp]$ gdb /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf
GNU gdb (GDB) Fedora 7.7.1-18.fc20
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-redhat-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf...done.
(gdb)
</nowiki>

=== Check debug symbols ===
Next try some simple commands to see whether GDB knows where symbols are located in the binary and source:

<nowiki>
(gdb) info line main
Line 43 of "/home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/cores/rtos/main.cpp" starts at address 0x8fe78 <main()> and ends at 0x8fe7a <main()+2>.
(gdb) list main
38
39 /*
40 * \brief Main entry point of Arduino application
41 */
42 int main( void )
43 {
44 init();
45
46 initVariant();
47
</nowiki>

If something goes wrong at this point you could try using the copy of GDB provided with the arduino tools instead, e.g. <code>arduino-1.5.7/hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb</code>

=== Attach GDB to OpenOCD ===
The OpenOCD supports a couple of different interfaces. Before we try GDB we should first stop the CPU using the basic control interface and tell it to halt the CPU:

<nowiki>
$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> halt
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0x000870ba psp: 0x20074a30
>
</nowiki>

To continue execution you can run "resume". Make sure you run "halt" to leave the target in the stopped before attaching GDB. Normally when GDB attaches it should stop the target automatically but this isn't working at the moment. If the target is running then you may when GDB attaches then you may see some odd behaviour.

The OpenOCD software runs a target server on localhost:3333 which we can ask GDB to attach to:
<nowiki>
(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
0x000870ba in prvCheckTasksWaitingTermination () at /home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
2839 while( uxTasksDeleted > ( UBaseType_t ) 0U )
(gdb)
</nowiki>

=== List FreeRTOS tasks ===
To list the running tasks you can use "info threads".

<nowiki>
(gdb) info threads
[New Thread 537348080]
[New Thread 537396632]
[New Thread 537402416]
[New Thread 537394216]
[New Thread 537405232]
[New Thread 537393096]
[New Thread 537348848]
[New Thread 537398824]
[New Thread 537400224]
[New Thread 537346984]
[New Thread 537403512]
[New Thread 537397728]
[New Thread 537395312]
Id Target Id Frame
14 Thread 537395312 (MessageCh) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
13 Thread 537397728 (RadioTran) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
12 Thread 537403512 (IMUTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
11 Thread 537346984 (TiLDATask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
10 Thread 537400224 (GUI) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
9 Thread 537398824 (LCD) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
8 Thread 537348848 (Tmr Svc) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
7 Thread 537393096 (RGBTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
6 Thread 537405232 (HomeScree) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
5 Thread 537394216 (BatterySa) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
4 Thread 537402416 (PMICTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
3 Thread 537396632 (RadioRece) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
2 Thread 537348080 (IDLE : : Running) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
* 1 Thread 537401320 (AppOpener) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
</nowiki>
Most threads should claim to be in "vPortYield()" which is one of the OS routines that a task will call when it wants to sleep for a while.Select a task and you can obtain its backtrace:
<nowiki>
(gdb) thread 6
[Switching to thread 6 (Thread 537405232)]
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
385 __asm volatile( "isb" );
(gdb) bt
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
#1 0x00085c60 in xEventGroupWaitBits (xEventGroup=0x20082b78, uxBitsToWaitFor=1, xClearOnExit=0, xWaitForAllBits=0, xTicksToWait=<optimized out>)
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/event_groups.c:357
#2 0x0008453e in HomeScreenApp::task (this=0x20082710) at /tmp/build9091009552223609902.tmp/HomeScreenApp.cpp:157
#3 0x000818b4 in Task::taskCaller (this=0x20082710) at /tmp/build9091009552223609902.tmp/Task.cpp:78
#4 0x00081906 in Task::_task (self=<optimized out>) at /tmp/build9091009552223609902.tmp/Task.cpp:87
#5 0x00086768 in ulPortSetInterruptMask () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:423
Backtrace stopped: previous frame identical to this frame (corrupt stack?)
</nowiki>
== Known issues ==
* <strike>Normally when you hit a breakpoint GDB will automatically switch to the thread that hit it. This is not happening at the moment. If you interrupt the code or hit a breakpoint you may have to manually switch threads. The 'info threads' puts "Running" next to task being executed and this is probably the one you need to switch to.</strike>
** Fixed by applying this patch to OpenOCD http://openocd.zylin.com/#/c/2303/
* When you attach and detach GDB doesn't automatically halt/resume the target. You can do this manually using the interface on port 3333 or just tell GDB to continue, then interrupt to stop it.
* GDB hits an assert if you detach the target and asks whether you want a core dump.
** This appears to be: https://sourceware.org/bugzilla/show_bug.cgi?id=12228
* I had a problem where the badge kept stopping at a breakpoint that I set in a previous GDB session and I was unable to fix it without power cycling the badge and restarting GDB & OpenOCD.

TiLDA Debugging using JTAG

2014-10-01T21:59:40Z

Marekventur: /* Alternative (Debian/Ubuntu) */

The TiLDA badge has a JTAG port which can be used to perform remote firmware debugging. With the right hardware and software you can use this to run a GDB session on your development machine to insert breakpoints, inspect memory and poke around with the firmware running on the badge just like it was a local process running on your machine.

== Prerequisites ==
''I started the list below with the parts that worked for me. Feel free to add alternatives if you know they work for you.''
* X86-64 Linux machine for building the firmware and running GDB
* TiLDA badge
** Plus micro USB cable for connecting TiLDA to development machine
* JTAG header, 10 way (2 x 5 pins) 0.05" (or 1.27mm) through hole
** e.g. Samtec FTS-105-01-L-D
** or Harwin M50-3500542 (part number from the TiLDA schematic)
* Fine tipped soldering iron
* [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex ARM-USB-TINY-H] USB JTAG Interface
** Plus USB type A to B cable (the original & large square plug)
* [https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/ Olimex ARM-JTAG-20-10] 20pin to 10pin adapter
* [http://openocd.sourceforge.net/ OpenOCD] software.
** This can control the Olimex JTAG interface and implements the GDB remote server protocol to talk with the debugger
* GDB
** I used gdb-7.7.1-18.fc20.x86_64.
* Arduino 1.5.7 tools
** For building & installing the firmware image

== Attach JTAG Header to badge ==
The header must be attached on the correct side of the board otherwise it won't work. The pins on the two sides of the header are slightly different, one side is tin coated and appears silver/grey. These are the ones you should be soldering. The gold plated side should to be used by the connector.

[[File:jtag-header.jpg|150px|thumb|center|text-top|JTAG header before being soldered on to the board]]
[[File:jtag-header-in-place-highlight.jpg|300px|thumb|center|text-top|TiLDA with new JTAG header highlighted]]

Flip the board upside down and solder pins from the LCD side. The pitch is only 1.27mm (0.05") which is half the size of most normal connectors so you need a steady hand. After you have soldered the pins it is a good idea to test for any short circuits before you power it on.

[[File:jtag-header-solder-side.jpg|200px|thumb|center|text-top|Header soldered on LCD side of the board]]

== Olimex adapter and USB-TINY-H ==
The cable from the Olimex adaper should be connected to the header so that the cable runs away from the board. Once again you may wish to check the connections appear to be the right way around, e.g. pin 1 on the adapter board connects to the 3v3 test point on the TiLDA. Connect the 20 pin side of the adapter into the main USB-TINY, this is keyed so it only fits one way around.

[[File:board-with-adapter.jpg|300px|thumb|center|text-top|TiLDA connected to Olimex TINY-Y]]

Plug the USB-TINY into a USB port on your machine. The 'dmesg' output should report something like:

usb 2-2: new high-speed USB device number 111 using ehci-pci
usb 2-2: New USB device found, idVendor=15ba, idProduct=002a
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: Olimex OpenOCD JTAG ARM-USB-TINY-H
usb 2-2: SerialNumber: OLXxxxxx

== Install OpenOCD ==
I started with the current version available in the Fedora package repository (openocd-0.7.0-3.fc20.x86_64). Other Linux distros are likely to have packaged too.

=== OpenOCD stack pointer bug ===
After I got everything running I noticed that the GDB backtraces would show the current function (PC) and the caller (LR) but all further stack entries were missing. After some debugging I found that OpenOCD was incorrectly calculating the stack pointer when it tried to align it. I applied a quick fix to disable the broken alignment code:

<nowiki>
--- openocd-0.7.0/src/rtos/rtos.c.bak 2014-09-14 17:28:10.000000000 +0100
+++ openocd-0.7.0/src/rtos/rtos.c 2014-09-14 17:29:39.000000000 +0100
@@ -454,12 +454,16 @@
tmp_str_ptr = *hex_reg_list;
new_stack_ptr = stack_ptr - stacking->stack_growth_direction *
stacking->stack_registers_size;
+#if 0
+ // This code gives bad results for already aligned pointers
+ // and negative stack growth
if (stacking->stack_alignment != 0) {
/* Align new stack pointer to x byte boundary */
new_stack_ptr =
(new_stack_ptr & (~((int64_t) stacking->stack_alignment - 1))) +
((stacking->stack_growth_direction == -1) ? stacking->stack_alignment : 0);
}
+#endif
for (i = 0; i < stacking->num_output_registers; i++) {
int j;
for (j = 0; j < stacking->register_offsets[i].width_bits/8; j++) {
</nowiki>

I reported the bug to the OpenOCD developers and proper fix will hopefully arrive in the trunk code soon: http://openocd.zylin.com/#/c/2301/ (an initial fix was committed but has since been reverted because it was broken for a different case).

====Alternative (Debian/Ubuntu) ====

To do this you can download the code from http://sourceforge.net/projects/openocd/files/openocd/0.8.0/ and apply this patch http://openocd.zylin.com/#/c/2301/3/src/rtos/rtos.c,cm .

<nowiki>
sudo apt-get install libusb-dev libusb-1.0-0-dev
./configure --enable-armjtagew
make
sudo make install
./configure
</nowiki>

== OpenOCD configuration file ==
OpenOCD requires a set of configuration commands describing both the JTAG adapter and the target CPU/board. Copy this into a file called tilda.cfg:

<nowiki>
# Recommended for OpenOCD-0.7
# script interface/olimex-arm-usb-tiny-h.cfg

# Recommended for OpenOCD-0.8
script interface/ftdi/olimex-arm-usb-tiny-h.cfg

# script for ATMEL sam3, a CORTEX-M3 chip
script target/at91sam3XXX.cfg

$_TARGETNAME configure -rtos FreeRTOS
</nowiki>

=== Run OpenOCD ===
OpenOCD uses libusb to access the device and may need to run with sudo for it to work. If everything is connected together and the badge is powered on then you should see it detecting the CPU core as shown below:

<nowiki>
$ sudo openocd -f tilda.cfg
Open On-Chip Debugger 0.8.0 (2014-09-17-20:52)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m reset_config sysresetreq
Info : clock speed 500 kHz
Info : JTAG tap: sam3.cpu tap/device found: 0x4ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x4)
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>

== Patch TiLDA firmware for OpenOCD FreeRTOS detection ==
The OpenOCD code knows how to find the FreeRTOS tasks and can use this to make each task running on the badge as a different thread in GDB. To make this work you need to apply a small patch to the TiLDA code.

<nowiki>
diff --git a/EMF2014/TiLDATask.cpp b/EMF2014/TiLDATask.cpp
index 2cdc08d..701f940 100644
--- a/EMF2014/TiLDATask.cpp
+++ b/EMF2014/TiLDATask.cpp
@@ -58,6 +58,8 @@
#include "logo.h"
#include "TiLDA_64x128.h"

+// Hack to make FreeRTOS support work in OpenOCD
+unsigned portBASE_TYPE uxTopUsedPriority;

TiLDATask::TiLDATask() {

@@ -68,6 +70,10 @@ String TiLDATask::getName() const {
}

void TiLDATask::task() {
+
+ // Hack to make FreeRTOS support work in OpenOCD
+ uxTopUsedPriority = configMAX_PRIORITIES - 1;
+
Tilda::_realTimeClock = new RTC_clock(RC);
Tilda::_appManager = new AppManager;
</nowiki>

This adds a variable that the OpenOCD expects to be able to read from the target to determine how many queues are being used by the FreeRTOS scheduler. This was present in older FreeRTOS release but has since been removed.

== Build and flash the badge firmware ==
To make the debugger work you must be sure that the firmware running on the badge exactly matches the source code and binary objects that you have locally on your development machine. I recommend you apply the patch from the previous section, build the TiLDA firmware and upload it to your badge before you go any further.

In the Arduino IDE you should build firmware (EMF2014 sketch) and upload it via the USB port on the TiLDA badge. (I have not attempted to upload firmware via the JTAG interface but that should be possible as well). The IDE writes a copy of the object files and the final executable to a directory in /tmp whenever you build the code. The firmware image file is <code>EMF2014.cpp.elf</code> and you want to find the most recently built one, e.g.

[jburgess@shark]$ ls -lt /tmp/build*/EMF2014.cpp.elf | head -n 1
-rwxrwxr-x. 1 jburgess jburgess 1475463 Sep 14 22:53 /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf

== Running GDB ==
First locate the EMF2014.cpp.elf file mentioned in the previous section. Run gdb with this file and with any luck it should be able to load it:

<nowiki>
[jburgess@shark tmp]$ gdb /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf
GNU gdb (GDB) Fedora 7.7.1-18.fc20
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-redhat-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf...done.
(gdb)
</nowiki>

=== Check debug symbols ===
Next try some simple commands to see whether GDB knows where symbols are located in the binary and source:

<nowiki>
(gdb) info line main
Line 43 of "/home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/cores/rtos/main.cpp" starts at address 0x8fe78 <main()> and ends at 0x8fe7a <main()+2>.
(gdb) list main
38
39 /*
40 * \brief Main entry point of Arduino application
41 */
42 int main( void )
43 {
44 init();
45
46 initVariant();
47
</nowiki>

If something goes wrong at this point you could try using the copy of GDB provided with the arduino tools instead, e.g. <code>arduino-1.5.7/hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb</code>

=== Attach GDB to OpenOCD ===
The OpenOCD supports a couple of different interfaces. Before we try GDB we should first stop the CPU using the basic control interface and tell it to halt the CPU:

<nowiki>
$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> halt
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0x000870ba psp: 0x20074a30
>
</nowiki>

To continue execution you can run "resume". Make sure you run "halt" to leave the target in the stopped before attaching GDB. Normally when GDB attaches it should stop the target automatically but this isn't working at the moment. If the target is running then you may when GDB attaches then you may see some odd behaviour.

The OpenOCD software runs a target server on localhost:3333 which we can ask GDB to attach to:
<nowiki>
(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
0x000870ba in prvCheckTasksWaitingTermination () at /home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
2839 while( uxTasksDeleted > ( UBaseType_t ) 0U )
(gdb)
</nowiki>

=== List FreeRTOS tasks ===
To list the running tasks you can use "info threads".

<nowiki>
(gdb) info threads
[New Thread 537348080]
[New Thread 537396632]
[New Thread 537402416]
[New Thread 537394216]
[New Thread 537405232]
[New Thread 537393096]
[New Thread 537348848]
[New Thread 537398824]
[New Thread 537400224]
[New Thread 537346984]
[New Thread 537403512]
[New Thread 537397728]
[New Thread 537395312]
Id Target Id Frame
14 Thread 537395312 (MessageCh) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
13 Thread 537397728 (RadioTran) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
12 Thread 537403512 (IMUTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
11 Thread 537346984 (TiLDATask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
10 Thread 537400224 (GUI) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
9 Thread 537398824 (LCD) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
8 Thread 537348848 (Tmr Svc) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
7 Thread 537393096 (RGBTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
6 Thread 537405232 (HomeScree) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
5 Thread 537394216 (BatterySa) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
4 Thread 537402416 (PMICTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
3 Thread 537396632 (RadioRece) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
2 Thread 537348080 (IDLE : : Running) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
* 1 Thread 537401320 (AppOpener) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
</nowiki>
Most threads should claim to be in "vPortYield()" which is one of the OS routines that a task will call when it wants to sleep for a while.Select a task and you can obtain its backtrace:
<nowiki>
(gdb) thread 6
[Switching to thread 6 (Thread 537405232)]
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
385 __asm volatile( "isb" );
(gdb) bt
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
#1 0x00085c60 in xEventGroupWaitBits (xEventGroup=0x20082b78, uxBitsToWaitFor=1, xClearOnExit=0, xWaitForAllBits=0, xTicksToWait=<optimized out>)
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/event_groups.c:357
#2 0x0008453e in HomeScreenApp::task (this=0x20082710) at /tmp/build9091009552223609902.tmp/HomeScreenApp.cpp:157
#3 0x000818b4 in Task::taskCaller (this=0x20082710) at /tmp/build9091009552223609902.tmp/Task.cpp:78
#4 0x00081906 in Task::_task (self=<optimized out>) at /tmp/build9091009552223609902.tmp/Task.cpp:87
#5 0x00086768 in ulPortSetInterruptMask () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:423
Backtrace stopped: previous frame identical to this frame (corrupt stack?)
</nowiki>
== Known issues ==
* <strike>Normally when you hit a breakpoint GDB will automatically switch to the thread that hit it. This is not happening at the moment. If you interrupt the code or hit a breakpoint you may have to manually switch threads. The 'info threads' puts "Running" next to task being executed and this is probably the one you need to switch to.</strike>
** Fixed by applying this patch to OpenOCD http://openocd.zylin.com/#/c/2303/
* When you attach and detach GDB doesn't automatically halt/resume the target. You can do this manually using the interface on port 3333 or just tell GDB to continue, then interrupt to stop it.
* GDB hits an assert if you detach the target and asks whether you want a core dump.
** This appears to be: https://sourceware.org/bugzilla/show_bug.cgi?id=12228
* I had a problem where the badge kept stopping at a breakpoint that I set in a previous GDB session and I was unable to fix it without power cycling the badge and restarting GDB & OpenOCD.

TiLDA Debugging using JTAG

2014-10-01T21:59:23Z

Marekventur: /* Install OpenOCD */

The TiLDA badge has a JTAG port which can be used to perform remote firmware debugging. With the right hardware and software you can use this to run a GDB session on your development machine to insert breakpoints, inspect memory and poke around with the firmware running on the badge just like it was a local process running on your machine.

== Prerequisites ==
''I started the list below with the parts that worked for me. Feel free to add alternatives if you know they work for you.''
* X86-64 Linux machine for building the firmware and running GDB
* TiLDA badge
** Plus micro USB cable for connecting TiLDA to development machine
* JTAG header, 10 way (2 x 5 pins) 0.05" (or 1.27mm) through hole
** e.g. Samtec FTS-105-01-L-D
** or Harwin M50-3500542 (part number from the TiLDA schematic)
* Fine tipped soldering iron
* [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex ARM-USB-TINY-H] USB JTAG Interface
** Plus USB type A to B cable (the original & large square plug)
* [https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/ Olimex ARM-JTAG-20-10] 20pin to 10pin adapter
* [http://openocd.sourceforge.net/ OpenOCD] software.
** This can control the Olimex JTAG interface and implements the GDB remote server protocol to talk with the debugger
* GDB
** I used gdb-7.7.1-18.fc20.x86_64.
* Arduino 1.5.7 tools
** For building & installing the firmware image

== Attach JTAG Header to badge ==
The header must be attached on the correct side of the board otherwise it won't work. The pins on the two sides of the header are slightly different, one side is tin coated and appears silver/grey. These are the ones you should be soldering. The gold plated side should to be used by the connector.

[[File:jtag-header.jpg|150px|thumb|center|text-top|JTAG header before being soldered on to the board]]
[[File:jtag-header-in-place-highlight.jpg|300px|thumb|center|text-top|TiLDA with new JTAG header highlighted]]

Flip the board upside down and solder pins from the LCD side. The pitch is only 1.27mm (0.05") which is half the size of most normal connectors so you need a steady hand. After you have soldered the pins it is a good idea to test for any short circuits before you power it on.

[[File:jtag-header-solder-side.jpg|200px|thumb|center|text-top|Header soldered on LCD side of the board]]

== Olimex adapter and USB-TINY-H ==
The cable from the Olimex adaper should be connected to the header so that the cable runs away from the board. Once again you may wish to check the connections appear to be the right way around, e.g. pin 1 on the adapter board connects to the 3v3 test point on the TiLDA. Connect the 20 pin side of the adapter into the main USB-TINY, this is keyed so it only fits one way around.

[[File:board-with-adapter.jpg|300px|thumb|center|text-top|TiLDA connected to Olimex TINY-Y]]

Plug the USB-TINY into a USB port on your machine. The 'dmesg' output should report something like:

usb 2-2: new high-speed USB device number 111 using ehci-pci
usb 2-2: New USB device found, idVendor=15ba, idProduct=002a
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: Olimex OpenOCD JTAG ARM-USB-TINY-H
usb 2-2: SerialNumber: OLXxxxxx

== Install OpenOCD ==
I started with the current version available in the Fedora package repository (openocd-0.7.0-3.fc20.x86_64). Other Linux distros are likely to have packaged too.

=== OpenOCD stack pointer bug ===
After I got everything running I noticed that the GDB backtraces would show the current function (PC) and the caller (LR) but all further stack entries were missing. After some debugging I found that OpenOCD was incorrectly calculating the stack pointer when it tried to align it. I applied a quick fix to disable the broken alignment code:

<nowiki>
--- openocd-0.7.0/src/rtos/rtos.c.bak 2014-09-14 17:28:10.000000000 +0100
+++ openocd-0.7.0/src/rtos/rtos.c 2014-09-14 17:29:39.000000000 +0100
@@ -454,12 +454,16 @@
tmp_str_ptr = *hex_reg_list;
new_stack_ptr = stack_ptr - stacking->stack_growth_direction *
stacking->stack_registers_size;
+#if 0
+ // This code gives bad results for already aligned pointers
+ // and negative stack growth
if (stacking->stack_alignment != 0) {
/* Align new stack pointer to x byte boundary */
new_stack_ptr =
(new_stack_ptr & (~((int64_t) stacking->stack_alignment - 1))) +
((stacking->stack_growth_direction == -1) ? stacking->stack_alignment : 0);
}
+#endif
for (i = 0; i < stacking->num_output_registers; i++) {
int j;
for (j = 0; j < stacking->register_offsets[i].width_bits/8; j++) {
</nowiki>

I reported the bug to the OpenOCD developers and proper fix will hopefully arrive in the trunk code soon: http://openocd.zylin.com/#/c/2301/ (an initial fix was committed but has since been reverted because it was broken for a different case).

====Alternative (Debian/Ubuntu) ====

To do this you can download the code from http://sourceforge.net/projects/openocd/files/openocd/0.8.0/ and apply this patch http://openocd.zylin.com/#/c/2301/3/src/rtos/rtos.c,cm .
<nowiki>
sudo apt-get install libusb-dev libusb-1.0-0-dev
./configure --enable-armjtagew
make
sudo make install
./configure
</nowiki>

== OpenOCD configuration file ==
OpenOCD requires a set of configuration commands describing both the JTAG adapter and the target CPU/board. Copy this into a file called tilda.cfg:

<nowiki>
# Recommended for OpenOCD-0.7
# script interface/olimex-arm-usb-tiny-h.cfg

# Recommended for OpenOCD-0.8
script interface/ftdi/olimex-arm-usb-tiny-h.cfg

# script for ATMEL sam3, a CORTEX-M3 chip
script target/at91sam3XXX.cfg

$_TARGETNAME configure -rtos FreeRTOS
</nowiki>

=== Run OpenOCD ===
OpenOCD uses libusb to access the device and may need to run with sudo for it to work. If everything is connected together and the badge is powered on then you should see it detecting the CPU core as shown below:

<nowiki>
$ sudo openocd -f tilda.cfg
Open On-Chip Debugger 0.8.0 (2014-09-17-20:52)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m reset_config sysresetreq
Info : clock speed 500 kHz
Info : JTAG tap: sam3.cpu tap/device found: 0x4ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x4)
Info : sam3.cpu: hardware has 6 breakpoints, 4 watchpoints
</nowiki>

== Patch TiLDA firmware for OpenOCD FreeRTOS detection ==
The OpenOCD code knows how to find the FreeRTOS tasks and can use this to make each task running on the badge as a different thread in GDB. To make this work you need to apply a small patch to the TiLDA code.

<nowiki>
diff --git a/EMF2014/TiLDATask.cpp b/EMF2014/TiLDATask.cpp
index 2cdc08d..701f940 100644
--- a/EMF2014/TiLDATask.cpp
+++ b/EMF2014/TiLDATask.cpp
@@ -58,6 +58,8 @@
#include "logo.h"
#include "TiLDA_64x128.h"

+// Hack to make FreeRTOS support work in OpenOCD
+unsigned portBASE_TYPE uxTopUsedPriority;

TiLDATask::TiLDATask() {

@@ -68,6 +70,10 @@ String TiLDATask::getName() const {
}

void TiLDATask::task() {
+
+ // Hack to make FreeRTOS support work in OpenOCD
+ uxTopUsedPriority = configMAX_PRIORITIES - 1;
+
Tilda::_realTimeClock = new RTC_clock(RC);
Tilda::_appManager = new AppManager;
</nowiki>

This adds a variable that the OpenOCD expects to be able to read from the target to determine how many queues are being used by the FreeRTOS scheduler. This was present in older FreeRTOS release but has since been removed.

== Build and flash the badge firmware ==
To make the debugger work you must be sure that the firmware running on the badge exactly matches the source code and binary objects that you have locally on your development machine. I recommend you apply the patch from the previous section, build the TiLDA firmware and upload it to your badge before you go any further.

In the Arduino IDE you should build firmware (EMF2014 sketch) and upload it via the USB port on the TiLDA badge. (I have not attempted to upload firmware via the JTAG interface but that should be possible as well). The IDE writes a copy of the object files and the final executable to a directory in /tmp whenever you build the code. The firmware image file is <code>EMF2014.cpp.elf</code> and you want to find the most recently built one, e.g.

[jburgess@shark]$ ls -lt /tmp/build*/EMF2014.cpp.elf | head -n 1
-rwxrwxr-x. 1 jburgess jburgess 1475463 Sep 14 22:53 /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf

== Running GDB ==
First locate the EMF2014.cpp.elf file mentioned in the previous section. Run gdb with this file and with any luck it should be able to load it:

<nowiki>
[jburgess@shark tmp]$ gdb /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf
GNU gdb (GDB) Fedora 7.7.1-18.fc20
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-redhat-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /tmp/build9091009552223609902.tmp/EMF2014.cpp.elf...done.
(gdb)
</nowiki>

=== Check debug symbols ===
Next try some simple commands to see whether GDB knows where symbols are located in the binary and source:

<nowiki>
(gdb) info line main
Line 43 of "/home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/cores/rtos/main.cpp" starts at address 0x8fe78 <main()> and ends at 0x8fe7a <main()+2>.
(gdb) list main
38
39 /*
40 * \brief Main entry point of Arduino application
41 */
42 int main( void )
43 {
44 init();
45
46 initVariant();
47
</nowiki>

If something goes wrong at this point you could try using the copy of GDB provided with the arduino tools instead, e.g. <code>arduino-1.5.7/hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb</code>

=== Attach GDB to OpenOCD ===
The OpenOCD supports a couple of different interfaces. Before we try GDB we should first stop the CPU using the basic control interface and tell it to halt the CPU:

<nowiki>
$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> halt
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x61000000 pc: 0x000870ba psp: 0x20074a30
>
</nowiki>

To continue execution you can run "resume". Make sure you run "halt" to leave the target in the stopped before attaching GDB. Normally when GDB attaches it should stop the target automatically but this isn't working at the moment. If the target is running then you may when GDB attaches then you may see some odd behaviour.

The OpenOCD software runs a target server on localhost:3333 which we can ask GDB to attach to:
<nowiki>
(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
0x000870ba in prvCheckTasksWaitingTermination () at /home/jburgess/Documents/emf/Mk2-Firmware/hardware/emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
2839 while( uxTasksDeleted > ( UBaseType_t ) 0U )
(gdb)
</nowiki>

=== List FreeRTOS tasks ===
To list the running tasks you can use "info threads".

<nowiki>
(gdb) info threads
[New Thread 537348080]
[New Thread 537396632]
[New Thread 537402416]
[New Thread 537394216]
[New Thread 537405232]
[New Thread 537393096]
[New Thread 537348848]
[New Thread 537398824]
[New Thread 537400224]
[New Thread 537346984]
[New Thread 537403512]
[New Thread 537397728]
[New Thread 537395312]
Id Target Id Frame
14 Thread 537395312 (MessageCh) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
13 Thread 537397728 (RadioTran) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
12 Thread 537403512 (IMUTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
11 Thread 537346984 (TiLDATask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
10 Thread 537400224 (GUI) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
9 Thread 537398824 (LCD) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
8 Thread 537348848 (Tmr Svc) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
7 Thread 537393096 (RGBTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
6 Thread 537405232 (HomeScree) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
5 Thread 537394216 (BatterySa) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
4 Thread 537402416 (PMICTask) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
3 Thread 537396632 (RadioRece) 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
2 Thread 537348080 (IDLE : : Running) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
* 1 Thread 537401320 (AppOpener) 0x000870ba in prvCheckTasksWaitingTermination ()
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/tasks.c:2839
</nowiki>
Most threads should claim to be in "vPortYield()" which is one of the OS routines that a task will call when it wants to sleep for a while.Select a task and you can obtain its backtrace:
<nowiki>
(gdb) thread 6
[Switching to thread 6 (Thread 537405232)]
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
385 __asm volatile( "isb" );
(gdb) bt
#0 0x00086750 in vPortYield () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:385
#1 0x00085c60 in xEventGroupWaitBits (xEventGroup=0x20082b78, uxBitsToWaitFor=1, xClearOnExit=0, xWaitForAllBits=0, xTicksToWait=<optimized out>)
at emfcamp/sam/libraries/FreeRTOS_ARM/utility/event_groups.c:357
#2 0x0008453e in HomeScreenApp::task (this=0x20082710) at /tmp/build9091009552223609902.tmp/HomeScreenApp.cpp:157
#3 0x000818b4 in Task::taskCaller (this=0x20082710) at /tmp/build9091009552223609902.tmp/Task.cpp:78
#4 0x00081906 in Task::_task (self=<optimized out>) at /tmp/build9091009552223609902.tmp/Task.cpp:87
#5 0x00086768 in ulPortSetInterruptMask () at emfcamp/sam/libraries/FreeRTOS_ARM/utility/port.c:423
Backtrace stopped: previous frame identical to this frame (corrupt stack?)
</nowiki>
== Known issues ==
* <strike>Normally when you hit a breakpoint GDB will automatically switch to the thread that hit it. This is not happening at the moment. If you interrupt the code or hit a breakpoint you may have to manually switch threads. The 'info threads' puts "Running" next to task being executed and this is probably the one you need to switch to.</strike>
** Fixed by applying this patch to OpenOCD http://openocd.zylin.com/#/c/2303/
* When you attach and detach GDB doesn't automatically halt/resume the target. You can do this manually using the interface on port 3333 or just tell GDB to continue, then interrupt to stop it.
* GDB hits an assert if you detach the target and asks whether you want a core dump.
** This appears to be: https://sourceware.org/bugzilla/show_bug.cgi?id=12228
* I had a problem where the badge kept stopping at a breakpoint that I set in a previous GDB session and I was unable to fix it without power cycling the badge and restarting GDB & OpenOCD.

TiLDA MKe

2014-09-10T19:05:52Z

Marekventur: /* Features and Functions */

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:IMG_0474.jpg|500px|right|thumb|Front]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

Please Note: There are a couple of minor hardware and some firmware issues that might be effecting your badge. If you've let the magic smoke out of your charge controller or have tried to re-flash and ended up with nothing but a couple of dimly glowing lights then DO NOT DESPAIR -It's recoverable and fixes, documentation and lots of firmware are still being produced :)

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with the previous badge all code and design files are available.

==Battery Warning==
'''Always make sure you plug your battery in the right way round!''' If you don't, the charge controller will let out its magic smoke and die / become damaged and die later. The badge itself will still work, but it wont have the ability to charge anymore.

We think this is the cause of the charge controller issues a small number of badges had at the event was due to this mistake being made during final assembly on-site.

'''Lithium Batteries are dangerous!''' While these batteries are better protected than the MK1 batteries, they are still scary. Do not short your battery, and if it starts bulging or gets punctured, '''DO NOT USE IT AGAIN''' and dispose of it properly.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become a member of a certain group)
** On MacOS this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woohoo - You just successfully uploaded code to your badge

=== Your first “Hello world” app ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

If you are still using the Arduino IDE at this point, note that it will not let you edit the .cpp and .h files that are needed to create Apps for the badge. To force the IDE to re-compile/re-read any files you've edited using an external editor, make sure to go to the File -> Preferences dialog box, and check the "Use external editor" checkbox.

=== Why are things so different from standard Arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard Arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headaches if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 115220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
* If sending code to the badge using the Arduino IDE "Upload" button fails, even though the /dev/ttyACM0 (linux com port) is there, just retry, twice if neccessary.

=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a Raspberry Pi with two Ciseco USB radios. We never had the chance to actually try it with a large number of badges in the same spot, so please don’t expect it to work perfectly.

=== Contribute ===
Send us a pull request via [https://github.com/emfcamp/Mk2-Firmware GitHub] - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronisation and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LEDs
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108), docs (http://code.google.com/p/glcd-arduino/source/browse/trunk/glcd/doc/GLCD_Documentation.pdf) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask. The bitmap format, by the way, is rather unconventional but there are a couple of utility scripts to convert popular formats down in the hacking section below - you can grab the SponsorsApp.h as an example and swap out the bitmap array with one of your choosing.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

Note that one function was not ported to the badge version of GLCD, "Printf", you'll have to cope without it.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

== Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
There's no way of sending messages in the current version of the firmware, sorry :(

== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

* Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]
* A Python script (via [https://twitter.com/trotmaster99 @trotmaster99]) that converts a monochrome bitmap image into a format suitable for the Tilda can be found [http://pastebin.com/8XeazQjT here].
* A similar script in Perl to create TiLDA MKe fullscreen bitmaps from XBM: -
<div style ="height:200px;overflow-x:hidden;overflow-y:auto;border: 4px solid orange;">
'''xbm2mke.pl by [[User:Msemtd]]'''
<nowiki>
#!perl -w
use strict;
# Little script to convert a regular XBM to TiLDA MKe bitmap
# only tested with fullscreen bitmaps!
# Hot file handle magic...
select((select(STDERR), $| = 1)[0]);
select((select(STDOUT), $| = 1)[0]);
sub t(@);
sub d($);
sub chug($);
my $f = shift;
#~ $f = 'blankish.xbm' if not $f;
if(not defined $f or not $f =~ /^(.*)\.xbm$/i){
die "Usage: gimme an XBM file dude!\n";
}
my $name = $1;
t "Reading file '$f'...";
my $data = chug($f);
t "OK";
my @lines = split /^/, $data;
@lines = grep{chomp; s/^\s+//; s/\s+$//; length;} @lines;
#~ t d \@lines;
my($width, $height) = (0,0);
my @head = @lines[0..5];
foreach(@head){
if(/_width\s+(\d+)/){$width = $1;}
if(/_height\s+(\d+)/){$height = $1;}
}
t "width x height = $width x $height";
my @k;
foreach(@lines){ push @k, split /,/; }
@k = grep { s/^.*(0x[0-9A-Fa-f]{1,2}).*$/$1/o; /(0x[0-9A-Fa-f]{1,2})/o } @k;
#~ t d \@k;
my $bc = scalar(@k);
t "Pulled out $bc hex bytes";
if($bc != $width * $height / 8) {
die "byte count $bc does not match that expected for w x h";
}
t "OK - reorder bytes for MKe bitmap";
my $wb = int($width/8) + (($width & 0x07) ? 1: 0);
t "width in whole bytes for $width pixels = $wb";
my @mke;
for(my $col = 0; $col < $wb; $col++){
for(my $row = $height - 1; $row >= 0; $row--){
my $idx = ($row * $wb) + $col;
my $val = $k[$idx];
#~ t "Column $col + Row $row = idx $idx = $val";
push @mke, $val;
}
}
my $out = "static const uint8_t ".uc($name)."_BM[] = {\n"
." $width, // width\n"
." $height , // height\n";
#~ $out .= join(", ", @mke);
while(scalar @mke){
$out .= join(", ", splice(@mke, 0, 16)).",\n";
}
$out .= "};\n";
# meh, just print it out
t $out;

sub t(@) {
foreach (@_) {
print STDOUT "$_\n";
}
}
sub d($) {
require Data::Dumper;
my $s = $_[0];
my $d = Data::Dumper::Dumper($s);
$d =~ s/^\$VAR1 =\s*//;
$d =~ s/;$//;
chomp $d;
return $d;
}
sub chug($) {
my $filename = shift;
local *F;
open F, "< $filename" or die "Couldn't open `$filename': $!";
local $/ = undef;
return <F>;
} # F automatically closed

</nowiki>
</div>

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-09-01T18:36:03Z

Marekventur: /* Flash Storage = */

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with previous badge all code and design files are available.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris
* Weather Forecast
* Schedule
* Can receive notifications about upcoming schedule items you're interested in. Visit schedule.emf.camp to set up your account.

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become member of a certain group)
** On Macos this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woohoo - You just successfully uploaded code to your badge

=== Your first “Hello world” App ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

=== Why are things so different from standard arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headache if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 115220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a raspberry pi with two ciseco usb radios. We never had the change to actually try it with that many badges in the same spot, so please don’t expect it to work perfectly.
=== Contribute ===
Send us pull request via github - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronization and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LED's
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

== Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
There's no way of sending messages in the current version of the firmware, sorry :(

== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-09-01T18:33:44Z

Marekventur:

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with previous badge all code and design files are available.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris
* Weather Forecast
* Schedule
* Can receive notifications about upcoming schedule items you're interested in. Visit schedule.emf.camp to set up your account.

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become member of a certain group)
** On Macos this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woohoo - You just successfully uploaded code to your badge

=== Your first “Hello world” App ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

=== Why are things so different from standard arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headache if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 115220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a raspberry pi with two ciseco usb radios. We never had the change to actually try it with that many badges in the same spot, so please don’t expect it to work perfectly.
=== Contribute ===
Send us pull request via github - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronization and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LED's
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

= Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
There's no way of sending messages in the current version of the firmware, sorry :(

== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-08-30T13:44:03Z

Marekventur: /* Radio */

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with previous badge all code and design files are available.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris
* Weather Forecast
* Schedule
* Can receive notifications about upcoming schedule items you're interested in. Visit schedule.emf.camp to set up your account.

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become member of a certain group)
** On Macos this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woho - You just successfully uploaded code to your badge
* For now, the code waits for a key on the usbserial debug before doing anything, open the serial monitor in Arduino, set the line endings to ‘Newline’ and press enter.

=== Your first “Hello world” App ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

=== Why are things so different from standard arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headache if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 11220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a raspberry pi with two ciseco usb radios. We never had the change to actually try it with that many badges in the same spot, so please don’t expect it to work perfectly.
=== Contribute ===
Send us pull request via github - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronization and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LED's
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

= Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
There's no way of sending messages in the current version of the firmware, sorry :(

== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-08-30T13:43:22Z

Marekventur: /* Firmware Documentation */

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with previous badge all code and design files are available.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris
* Weather Forecast
* Schedule
* Can receive notifications about upcoming schedule items you're interested in. Visit schedule.emf.camp to set up your account.

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become member of a certain group)
** On Macos this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woho - You just successfully uploaded code to your badge
* For now, the code waits for a key on the usbserial debug before doing anything, open the serial monitor in Arduino, set the line endings to ‘Newline’ and press enter.

=== Your first “Hello world” App ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

=== Why are things so different from standard arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headache if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 11220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a raspberry pi with two ciseco usb radios. We never had the change to actually try it with that many badges in the same spot, so please don’t expect it to work perfectly.
=== Contribute ===
Send us pull request via github - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronization and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LED's
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
=== Tilda::getOrientation ===
returns " ORIENTATION_HELD", "ORIENTATION_RIGHT" (joystick to the right of the screen), "ORIENTATION_HUNG" or "ORIENTATION_LEFT"

= Flash Storage ==
We have 2mb of flash storage, but we're not using it in the main firmware - Please get this working!
== Data: Schedule ==
===Tilda::getDataStore().getSchedule(day, location) ===
== Date: Weather Forecast ==
===Tilda::getDataStore().getWeatherForecast()===
== Radio ==
== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-08-30T13:33:05Z

Marekventur: /* Hacking */

The TiLDA MKe project, Code name "ElectroMagnetic Boogaloo", is being headed by [[User:Dpslwk|'RepRap' Matt]] and [[User:thinkl33t|Bob]]
[[File:Badge_Front.png|right|thumb|Front]]

[http://en.wikipedia.org/wiki/E_(mathematical_constant) Why MKe?]

=Aim=
The main aim of the 2014 badge is to give camp attendees live schedule updates and notifications. As with the original TiLDA we wanted to keep with an Arduino compatible platform that will allow badge hacking during and after the camp. As with previous badge all code and design files are available.

==Features and Functions==
[[File:Badge_Back.png|right|thumb|Back]]
* Torch mode - Press the light button next to the screen. It will only light up fully if it's hung upside down to avoid blinding
* Snake
* Tetris
* Weather Forecast
* Schedule
* Can receive notifications about upcoming schedule items you're interested in. Visit schedule.emf.camp to set up your account.

'''Please note that there's a known issue with the badge freezing'''. We're trying to work out what's causing this, but in the meantime pressing "reset" should get the badge back to life. Help with debugging is highly welcome!

== How to get going ==
=== Set up your environment ===
* Plug your badge into your computer via USB
* Download Arduino IDE 1.5.7 from http://arduino.cc/en/main/software#toc3
* “git clone” or download TiLDA source code from https://github.com/emfcamp/Mk2-Firmware
* Start the Arduino IDE.
* Now you have to change the sketchbook-folder to be the folder you just cloned. To do this use File | Preferences | “Set Sketchbook location”. On MacOS, this is Arduino | Preferences
* Restart the Arduino IDE
* Open sketch “EMF2014”
* Set Tools | Board to MKe v0.333 (RTOS Core)
* Set Tools | Port to correct port (you might have to research this - some operating systems like Windows require you to install drivers or become member of a certain group)
** On Macos this is will start /dev/tty.usbmodem with 4 digits, and change for each port
** On Linux this is usually /dev/ttyACM0 but may be a higher number if you have other USB Serial devices
* Hit the upload button
* Wait
* Woho - You just successfully uploaded code to your badge
* For now, the code waits for a key on the usbserial debug before doing anything, open the serial monitor in Arduino, set the line endings to ‘Newline’ and press enter.

=== Your first “Hello world” App ===
There’s a “HelloWorldApp.cpp” file in which you can play around. In order for it to show up on the Homescreen you have to uncomment line 51 in AppManager.cpp and flash the changed code to the badge. Great app pull requests are appreciated!

=== Why are things so different from standard arduino code? ===
We’re using a library called FreeRTOS that allows us to multitask - something that’s normally not possible with standard arduino code. This allows us to run multiple tasks at the same time. FreeRTOS uses preemptive scheduling to switch between the task. Due to this we have to be very careful about how we do some things. For example we can’t just define interrupts for buttons in every task (imagine the mess!) or write to the serial port directly (your task might stop in the middle of the message).

We’ve also spend quite a lot of time to make the build-in components as easy to use as possible without having every task to write lots of boilerplate code. If you feel like using the build-in components on the badge, chances are we already wrote a wrapper for them that is already used by one of the other tasks.

Have a look at the “Documentation” section in this document for a full list of API functions. You will avoid a lot of headache if you stick to those.
=== How to use the badge with pure Arduino code ===
If you prefer you can always start from scratch without FreeRTOS or any of our code, just keep in mind that you won’t be able to receive messages via radio or use any of the API features we already added. Just start a new sketch in the Arduino IDE for that and get going. If you want to load the main firmware again just change the sketch to “EMF2014” and upload again.
=== Debugging and Gotchas ===
* The USB serial is set up to 11220 baud. There are lots of terminals that can connect to them
* If you can’t revive a badge you can short the two erase pins and press the reset button while holding it down.
* Avoid busy waiting, use FreeRTOS queues and Tilda::delay() instead
* Don’t use low level functions like interrupts or serial ports directly unless you really, really know how FreeRTOS will handle them. For general logging you can use Tilda::log()
=== Code structure ===
* FreeRTOS has the concept of “Tasks” which work like threads. We’ve wrappered them in a class called “Task” (for background stuff) and “Apps” (for foreground, one-at-a-time things)
* Everything needs to be in the main EMF2014 folder. Subfolders are not allowed. This is an Arduino IDE restriction :(
=== Radio infrastructure ===
The radio infrastructure is distributed between DKs. Every “gateway” has a raspberry pi with two ciseco usb radios. We never had the change to actually try it with that many badges in the same spot, so please don’t expect it to work perfectly.
=== Contribute ===
Send us pull request via github - We’ll do our best to review and merge the good ones during EMF so others can use them.

=Hardware=

The following hardware has been included on the badge.

* [http://www.atmel.com/products/microcontrollers/arm/sam3x.aspx Atmel ATSAM3X8E]
** This is the same chip as the [http://arduino.cc/en/Main/ArduinoBoardDue Arduino Due] and gives us the base platform for the badge
** 32bit ARM Cortex M3 * 84MHz
** 512KBytes Flash RAM
** 96KBytes of SRAM
* A 128x64 pixel monochrome LCD display
* [http://shop.ciseco.co.uk/srf-wireless-rf-radio-surface-mount/ Ciseco SRF Radio]
** 868Mhz RF Transceiver
** Simple UART interface
** Low power sleep mode
* [http://www.invensense.com/mems/gyro/mpu6050.html MPU-6050] 3-axis Accelerometer and 3-axis gyro
** I2C interface
** Tri-Axis angular rate sensor (gyro) with a sensitivity up to 131 LSBs/dps and a full-scale range of ±250, ±500, ±1000, and ±2000dps
** Tri-Axis accelerometer with a programmable full scale range of ±2g, ±4g, ±8g and ±16g
** Digital Motion Processing™ (DMP™) engine offloads complex MotionFusion, sensor timing synchronization and gesture detection
* PMIC & LiPo
* Joystick
* Buttons
* RGB LED's
* IR
* Arduino Headers
* Pads for wearable tech

= Firmware Documentation =
== Debugging ==
===Tilda::log(String text)===

This logs “text” to the serial console. To read it connect to it via the Arduino IDE Serial Monitor. Don’t use “SerialUSB.println” or similar -- it’s not thread-safe and you might end up with utter nonsense.
== Buttons ==
The badge has 8 buttons: Up, Down, Left, Right, Center (on the joystick), A, B and Light. You can use arduino-style “digitalRead(BUTTON_RIGHT)” to read the current status of any button, but you can’t define your own interrupt (because we already did that). This doesn’t mean you can’t wait for a certain button to be pressed, it just means you have to approach it slightly differently:

Example: A simple app displaying the button code
void ButtonApp::task() {
ButtonSubscription allButtons = Tilda::createButtonSubscription(LIGHT | A | B | UP | DOWN | LEFT | RIGHT | CENTER);

while(true) {
Button button = allButtons.waitForPress(1000);
if (button == A) {
debug::log(“You pressed button A”);
} else if (button == LEFT) {
debug::log(“You pressed LEFT”);
} else if (button == NONE) {
debug::log(“No button has been pressed in 1000ms”);
}
}
}

===ButtonSubscription Tilda::createButtonSubscription(<buttons>)===

Registers a subscriptions for a defined set of buttons and returns a ButtonSubscription. Multiple Buttons can be combined via “|” (see example above). One button can not be subscribed by more than 10 subscriptions (which shouldn’t really happen, but keep it in mind).

Don’t use this function in a constructor, it requires FreeRTOS to be running. Using it inside the task() function is the only safe place for it.

===Button ButtonSubscription::waitForPress(TimeInTicks timeout)===

This is normally called in a loop. It causes the task to block until one of the buttons has been pressed. If the timeout occurs before any button has been pressed “NONE” will be returned.

===ButtonSubscription::waitForPress()===

The same as above, but without the timeout.

===ButtonSubscription::clear()===

This should be called after an App has been suspended, just before it’s going to be resumed. It causes the Queue to be cleared which could otherwise lead to buttons being reported that have been pressed while other apps were in the foreground. Have a look at the FlashLightApp for an example.

==LEDs==
===Tilda::setLedColor(Led led, Color color);===
===Tilde::setLedColor(Color color);===

Sets the color of all or one led. Color is an object that takes red, green and blue as a value between 0 and 255 each. If no led is defined both leds will be set to the same color.

Example: A simple color-changing task
void ColorfulTask::task() {
while(true) {
Tilda::setLedColor(LED1, {255, 0, 0}); // Red
Tilda::setLedColor(LED2, {0, 255, 0}); // Green
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 255, 0}); // Green
Tilda::setLedColor(LED2, {0, 0, 255}); // Blue
Tilda::delay(300);
Tilda::setLedColor(LED1, {0, 0, 255}); // Blue
Tilda::setLedColor(LED2, {255, 0, 0}); // Red
Tilda::delay(300);
}
}

==Display==

The Display Library is based on GLCDv3 (http://playground.arduino.cc/Code/GLCDks0108) but adapted to support our screen. The Init routine is called in the setup, and the LCDTask takes care of ensuring the screen is updated every 40ms if required (Unlike the original GLCD library, screen updates are decoupled from the graphics routines.)

Also available is M2tklib (https://code.google.com/p/m2tklib/) which is a nice toolkit library. Further details on using this will come later, but expect the main loop to be handled for you, and just passing the menu structure you require for your app.

Right now, you can call the GLCD functions directly with GLCD.DrawBitmap() for example. This is going to change to be accessed through the GUITask class in the near future, to ensure only one task at a time writes to the screen. Expect this to be simply GUITask in place of GLCD, along with a registering a redraw call back to GUITask.

Extra features that are included, GLCD.SetRotation() will handle rotation of the screen for you, and GLCD.CurrentWidth() and GLCD.CurrentHeight will give you the correct Width and Height for the current orientation. GLCD.Width and GLCD.Height constants are not available, and the GLCD predefined Text areas will not be rotated for you, if you require this define your own text areas.

== Sound ==
There's a piezo on the board, but we haven't added code for it to the current firmware. Pull requests are very welcome!

== IMU ==
== Flash Storage ==
== Data: Schedule ==
== Date: Weather Forecast ==
== Radio ==
== Time ==

=== Tilda::delay(uint16_t delayInMs) ===

Works like Arduino’s delay(), but is FreeRTOS-safe. It’s safe to use this function before FreeRTOS has started.

=== tilda::getClock() ===

Returns an instance of https://github.com/MarkusLange/Arduino-Due-RTC-Library/blob/master/rtc_clock.h

==Settings==
===uint16_t tilda::getBadgeId()===

==2.12. Battery==
===float TiLDA::getBatteryVoltage()===
Returns the current voltage as a float

===uint8_t TiLDA::getBatteryPercent()===
Returns the current voltage as a percentage

===uint8_t TiLDA::getChargeState()===
Returns the charge state

0 Charging
1 Not Charging

== Apps ==
===Tilda::openApp(String appName)===

Opens an app with the given name. Make sure the name matches exactly the one defined in the task’s “getName()” function. If the app is not the currently-running one then the other one will be suspended first.

=Hacking=
To use our board definition you will need to first get the Arduino 1.5.7 IDE from [http://arduino.cc/en/Main/Software#toc3 here]<br/>
Next you can download the TiLDA MKe Firmware project from either the [https://github.com/emfcamp/Mk2-Firmware github repo] or via [https://github.com/emfcamp/Mk2-Firmware/archive/master.zip direct download]<br/>
Now copy the "hardware" folder to your Sketchbook folder, this is usually ~/Sketchbook/<br>
or<br/>
Alternative option is to set the Arduino 1.5.7 sketchbook folder to the Mk2-Firmware directory.<br/>

Start the Arduino IDE and your will be able to select TiLDA MKe v0.333 for the Tools->Board menu

Draft 3d print-able and laser-able case files [http://www.thingiverse.com/thing:436815 here]

<span id=github></span>

= Source =

All the source code and designs are on openly available on Github:

* [https://github.com/emfcamp/Mk2-Hardware Hardware] - the full board design
* [https://github.com/emfcamp/Mk2-Documentation Documentation] - a dump of relevant parts datasheets
* [https://github.com/emfcamp/Mk2-Firmware Firmware] - source code for the badge software
* [https://github.com/emfcamp/Mk2-Software Software] - server-side software for the network

[[Category: Badges]]

TiLDA MKe

2014-08-30T13:26:13Z

Marekventur: /* Set up your environment */

TiLDA MKe

2014-08-30T13:25:56Z

Marekventur: /* Features and Functions */

TiLDA MKe

2014-08-30T13:25:18Z

Marekventur: /* Features and Functions */

TiLDA MKe

2014-08-30T13:22:18Z

Marekventur:

Volunteers

2014-06-21T16:14:58Z

Marekventur:

{{link-banner}}

Don't put your name here unless you really mean it and don't edit other people's words without their permission.

This is a page in addition to signing up to volunteer as part of the ticket buying process. Please make sure that you have bought a ticket and signed up using that method as the emails gathered there will be how we contact everyone.

NOTE: unless you're volunteering as a first aider (and have confirmed ahead of time with the first aid team) you must buy a ticket.

{| class="wikitable"

|-
|'''Wiki user'''||'''[[Volunteers/DrivingLicenceCategories|Driving licence categories]]<br/>(if willing to drive)'''||'''I'd like to'''||'''I'm willing to'''


|-
|
[[User:NAB|NAB]]
|
B, BE, C1, C1E, D1, D1E (clean)
|

* Take ownership of caravan/motorhome/trailer-tent section of site (selection of initial location, mark-up, marshalling, liaison re power/potable water/greywater/blackwater etc.)
* Create "I'm shy/alone, please talk to me" type badges
* Offer telephone conference room(s) with SIP, geo and freephone access
* Offer on-site telecoms
|
* Drive minibuses
* Run shop (basic staples)
* Keep loos stocked with toilet roll
* Pretty much anything else



|-
|
[[User:lohapuk|lohapuk]]
|
A,B, B1 (clean)
|
* Help Deploy wireless / wired network (Certs CCNP,RHCE)
* Help Build tents / camp
|
* Anything to help out



|-
|
[[User:Sling|Sling]]
|
B (but Dutch)
|
* Help with info/noc helpdesk
* Buildup and teardown
* Sysadmin
* Wiki maintaining & structuring
|
* Parking/Security
* Barshifts
* Help with cooking
* Probably more stuff I'm forgetting.



|-
|
[[User:Dpslwk|'RepRap' Matt]]
|
Nope
|
* Badge Team, already working on it [[TiLDA 2]]
* Buildup and teardown (thought mostly i expect to be sorting badge related stuff, like deploying the R-PI radio network)
|
* Anything in between Badge hacking and running the Workshop area



|-
|
[[User:User_4574|Nathan Lasseter]]
|
B,B1,f,k,p (clean)
|
* Help with the NOC team (LAIT1 Accredited)
* Lay/fly cabling/fibre
* Buildup and teardown
|
* Do most things once



|-
|
[[User:danrl|danrl]]
|
B, C1, C
|
* deploy wireless / wired network
* build-up and tear-down
* IPv6 / NAT64
* Colocation
* Making teh NOC tent a fancy place to chill^M^Mwork hard
|
* rescue golf carts from ditches



|-
|
[[User:markp|markp]]
|
B, B1, f, k. p (clean)
|
* network / power cabling & termination
* build-up and tear-down
* transport (have estate car and trailer)
* lighting
* have access to mifare card/badge printing facilities
* assist with camping facilities
|
* help out wherever I'm needed
(can only be on-site Friday to Monday, but happy to help weekend before)



|-
|
[[User:bigcw|bigcw]]
|
B, B+E
|
* Get involved. Will help with anything. Very good at 'getting things done'.
|
* Connectivity (15 years experience in ISP industry)
* Power (former event lighting engineer)
* Transport (have Range Rover and trailer license)
* Anything else (lots of local knowledge, contacts, etc)



|-
|
[[User:simonvc|Simon Vans-Colina]]
|
A,B,BE,B2,f,k,p
|
* Anything really
|
* Dont have a car, but can drive one if needed.



|-
|
[[User:Si1entDave|Dave Wilson]]
|
B, B1
|
* Most things involving cables - I am also known as SparkyDave, head of site electrics for Profound Decisions LRP events
* My attendance will be contingent on my employer, Warwicknet, providing the connectivity - in which case they will give me the time off to attend :-)
* I also have a Defender which I am rather good at using to position trailers/generators/etc on fields
|
* I'll muck in with most things, but definitely specialise in electrics and networking.



|-
|
[[User:gmc|gmc]]
|
B, AM
|
* drive a manitou
* man the HQ
* do radio
* organize stuff
* A/V related stuff
* all of the above preferably in a supervisory / gophery kinda way
* build-up / tear-down
|
* pick up trash
* herald a lecture venue
* driving
* bar-shifts
* ...



|-
|
[[User:sleepycal|sleepycal]]
|
B,B1 (clean)
|
* Anything network related (NOC support, cabling, maintenance etc)
* Any aspect of site build-up/tear-down
* Prep work / planning
* Anything workshop related
* On-site help/emergency team (someone you can flag down any time/place if you need help)
|
* Anything to help out



|-
|
[[User:Big Kate|Big Kate]]
|
B, BE, C1, C1E, D1, D1E, Blue Badge
|
* Heralding/Speaker desk - On the day introduction to events etc
* Green Room Team:Content - Building a green room
* Making sure presenters have met there Heralds, hand off process etc
* Team:Rehash - Assuming its the same crew from OHM
* Queering the community i.e. LGBT etc community aspects
* Disability Access issues
|
* Build up and tear down
* (as best I can - given my disabilities)
* Drive Vehicles - upto 7.5 Tonnes
* (I have a disabled/ blue badge)
* (easier parking/ pickup/ drop off)
* Logistics and Operations
* Usual gophering type stuff



|-
|
[[User:drrk|Kimball]]
|
None
|
* <s>Buildup</s>Due to change of job I can't be there before the Friday now :(
* Badge Firmware
* Sysadmin
* AV/Radio
|
* Anything else


|-
|
[[User:Critical|Critical]]
|
B, BE, C1, C1E, D1, D1E
|
* Build up and tear down
* Anything Network / IT / AV related
* Meet / greet / help
|
* Whatever is needed


|-
|
[[User:chris_martin|chris_martin]]
|
0
|
* Build up and tear down
* FULLY SIA LICENSED >>> marshaling
* bar-shifts
|
* Whatever is needed


|-
|
[[User:lozarythmic|lozarythmic]]
|
AM, A, B, B1 (clean)
|
* Networking
* Fire Marshall
* Bar Work
|
* Whatever is needed


|-
|
[[User:JimM|Jim MacArthur]]
|
|
* Build up/tear down
* Bar Work
|
* Whatever is needed


|-
|
[[User:RattyMaHatty|Ratty]]
|
B, BE, C1, C1E, D1, D1E, fklnp (a few points)
|
* M$ Windows fixing
* PC/Server hardware engineer
* Networking
* Bar Work
* Driving
|
* Whatever is needed


|-
|
[[User:ens|ens]]
|
None - but willing ;)
|
* Media/Editing stuff (Can provide lend of broadcast-standard video gear if needed, aswell as editing gear)
* You need an electro-hacker-trippy-ambient DJ? hook me up.
* Build-up or Tear-down.
* Heralding.
* Helping those who are giving talks to get sorted.
|
* Help sourcing physical resources for the site.


|-
|
[[User:pioneer|pioneer]]
|
B,B+E,kfp (clean)
|
* Help Deploy wireless / wired network - Anything network related.. I have my own RJ45 Cripmer :p
* Help with VoIP system if deployed
* Sysadmin, NOC Help, Server admin
* Power, Lighting, AV - Part time sound engineer with access to PA systems, AV gear, projectors etc
* Build-up and tear-down
|
* I can loan a PA System
* can also loan networking/wifi + server equipment if needed, just ask and I might have it.
* I'll Help with most things, but I specialise in electrics, networking / server admin.


|-
|
[[User:AK47|AK47]]
|
B
|
* NOC
* WiFi
* VoIP
* General networking stuff
|
* Anything else


|-
| [[User:Pure|Joe Roberts]]
| None
|
* Help desk (WiFi connecting, server stuff, techy stuff!)
* Build up and tear down
* Talking to people
* (DBS Approved)
| Anything I can possibly do!


|-
|
[[User:immunda|Phil Howell]]
|
B1, B, f, k, p (clean)
|
* Help out with driving (has estate car if helpful)
* A/V stuff (have PA gear that can be used)
* Help with networking stuff
|
* Whatever is needed



|-
|
[[User:BuildTheRobots|Daniel Fligg]]
|
AM, A, B1, B, (f,k,p,q) (clean, since April 08)
|
* Enjoys driving
* Experience running PAs / Bands
* Networks & Communications (Team:Phone)
* Lots of marshaling experience.
|
* Whatever else is needed



|-
|
[[User:Arran|Arran Gallagher]]
|
None
|
* Help with the NOC
* Deploy wireless / wired network
* Sysadmin
|
* Help with build up and tear down
* Provide assistance to attendees



|-
|
[[User:ianthe88|Ianthe Sutherland]]
|
None
|
* Have a first aid certificate so happy to be noted as a first aider
* Meet & greet
|
* Whatever is needed



|-
|
[[User:greenhac|PeterJ]]
|
-
|
* Security/Car Park (EMF 2012 Security Alumnus)
|
* Whatever needs doing



|-
|
[[User:StuartL|StuartL]]
|
A, B, BE, C1, C1E, D1, D1E, f, k, l, n, p (clean)
|
* Drive minibuses/shuttle people generally
* Drive pretty much anything on/off road, incl heavy equipment
* Do Netwerk Shtuff
|
* Drive/operate/recover vehicles
* Design/implement network
* Provide network switch(es), cables
* Provide vehicle with tow-bar, if it's useful
* Provide generator (2.5kVA)



|-
|
[[User:mdg|mdg]]
|
N/A
|
* Bar Work
|
* Sysadmin if needed



|-
|
[[User:pobk|pobk]]
|
B1/B/f/k/p/q (Clean)
|
* Where required
* I volunteer for St John Ambulance and hold advanced first aid quals (Medgasses, AED, spinal, fractures etc). Happy to provide medical cover... May even be able to drag long kit.
|
* Whatever needs doing.



|-
|
[[User:mattg|mattg]]
|
B1/B/f/k/p/q (Clean)
|
* Drive things
* Help with infrastructure
* anything else that needs doing.
|
* Help with AV/stage stuff + streaming/recording etc.
* be friendly face to punters
* may be available for some of get-in.
* Whatever else needs doing.



|-
|
[[User:Mpresson|mpresson]]
|
A, B, BE, C1, C1E, D1, D1E, f, k, l, n, p (clean)
|
* Drive minibuses/shuttle people generally
* Bar work
|
* Pretty much anything within reason



|-
|
[[User:w1bble|w1bble]]
|
B, C1E, D1E (clean but a scrap of messy old paper)
|
* Be local to EMF [[Bletchley]] so can help before & poss after
* Take pictures
* Sysadmin if needed
* Be responsible for $offspring1 (Oliver age 11)
|
* Pretty much anything within reason (noting offspring requirement)



|-
|
[[User:Chewie|Chewie]]
|
B, C1E, D1E
|
* Networking
* Bringing a truck that can tow things that will fit onto a [http://www.johnrichardssurplus.co.uk/content/images/xxl/129.jpg NATO hitch]
|
* Pretty much anything technical :)
* Bringing a generator (at least 4kw), which is thirsty, but useful for emergencies



|-
|
[[User:marekventur|marekventur]]
|
B
|
* I can be there early that week and help with building up the camp/infrastructure
* Happy to help out with stewarding and whatever else needs doing during the camp
|
* Help with badges if any work is needed