EMF Badge - User contributions [en]

TiLDA MK3/Firmware Update

2016-08-11T10:12:07Z

Liedra: /* Before you start */

== Update your Tilda Mk3==

This websites will help you to update your Tilda Mk3 badge. But be careful, following these instructions will delete all files and setting on your badge, so make sure you have copies of everything!

== Before you start==

You need to put your badge into DFU mode. To do this please press down the joystick button in the center while at the same time quickly pushing the reset button at the back.

Your screen should go white and then you'll now be ready to update your badge. Note: screen does not always go white, but should go into DFU mode, so if you do the right button presses try it and see.

==OSX==

'''Prerequisites needed for Mac OS X'''

1. XCode (from App Store)

2. [http://docs.python-guide.org/en/latest/starting/install/osx/ Homebrew and Pip]

3. You then need to (from the terminal) use homebrew to install libusb <code>brew install libusb</code> and pip to install libusb1 and pyusb <code>pip install libusb1 pyusb</code>

4. You should be good to go!

Open a terminal and execute this line:

<code>curl --silent --show-error --retry 5 https://update.badge.emfcamp.org/update.py | python</code>

== Linux ==

Open a terminal and execute this line:

<code>curl --silent --show-error --retry 5 https://update.badge.emfcamp.org/update.py | python</code>

== Windows ==

On a Windows PC, you will need to download the STMicroelectronics DfuSe USB device firmware updater software http://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-stm32080.html and use the 'Upgrade or Verify Action' part of the GUI to update the firmware instead.

* Install the STMMicroelectronics util from the link above.
* Download the firmware.dfu file from https://update.badge.emfcamp.org/firmware.dfu and save it off.
* Start up DfuSeDemo.exe, and click the 'Choose' button - select the firmware.dfu file and then hit 'Upgrade'
* Your firmware will now be updated.

== Other Operating systems==

To update your badge please download the following script and run it via python: [https://update.badge.emfcamp.org/update.py update.py]

If you know how to flash the badge yourself you can also download the DFU binary directly: [https://update.badge.emfcamp.org/firmware.dfu firmware.dfu]

== Build your own version==

If you want to build your own version of the firmware have a look [https://badge.emfcamp.org/wiki/TiLDA_MK3/build here]

TiLDA MK3/Get Started

2016-08-09T07:55:46Z

Liedra: /* 6. (Optional) Update your badge's micropython */

= Get started =

Hacking your TiLDA badge is easy. We've written it down step by step.

If something goes wrong, the badge can be [[TiLDA_MK3/reset|reset]] to its out-of-the-box state, so do not be concerned about breaking anything.

== 1. Connect to your computer ==
To get started you need to connect your badge to a computer. You can use any MicroUSB cable - the same type that charges most mobile phones nowadays. It doesn't matter whether the batter is plugged in or not, so don't worry about it.

== 2. Check your badge is found by your computer ==
Upon connecting the badge to a computer, it should appear as a "mass storage device" just like a USB key or an external hard disk.

'''Important:''' Just like any other USB storage device, if you changed or copied anything on the Badge, please make sure to "eject" or "safely remove" before unplugging your badge or pressing the reset button. Otherwise you might lose all your work :(

Windows will require a driver file for the serial port, which is stored on the badge's mass storage. [https://micropython.org/resources/Micro-Python-Windows-setup.pdf More information]

== 3. Connect to your badge ==

=== Windows ===
* Please follow the instruction under the "Windows" section on this page: https://micropython.org/doc/tut-repl
* Once you've installed the driver and Putty and you've connected to your badge, press Control+C to stop the main badge app, and then you should be greeted by a line saying "Micropython"

=== OSX ===
* Click the magnifying class in the top right of your screen and type <code>Terminal</code> followed by Enter. A white terminal window should appear.
* type <code>screen /dev/tty.usbmodem*</code> (The * is important, so don't let it out) and hit enter
* hit <code>control+c</code>, if an error is displayed
* You should now be greeted by a line saying "Micropython"

=== Linux ===
* Open a terminal and type <code>screen /dev/ttyACM0</code>
* You should now be greeted by a line saying "Micropython"

=== What to do if this step doesn't work? ===
* Press the reset button at the back of your badge and try again
* Have a look at https://micropython.org/doc/tut-repl for more information

== 4. Your first line of Micropython ==
* In your terminal (next to the >>>) type <code>print(1 + 1)</code> followed by Enter
* You should see <code>2</code> printed on the screen. Congratulations, you've just written your first line of micropython code!
* You can now close the terminal window (or Putty, if you're on Windows). Note: some serial terminals will not close when the badge is removed or powered off. You should close the serial terminal before plugging the badge back in, otherwise the serial terminal may not reconnect.

== 5. Download some software you'll need ==

You will be downloading some stuff now. It's probably be best if you create some folder somewhere so you don't end up with files all over your Desktop.

Note you can copy files across from your computer to the badge, reset the badge and run the files though the menu, however these instructions make things a little easier.

=== Windows ===
* Python: Go to https://www.python.org/downloads/ and download python version 3.x. After the download is finished you can install it.
* Go to https://bootstrap.pypa.io/get-pip.py and save the file into your folder
* Hold shift, right click on the folder on, and click "open command window here"
* Now type <code>python get-pip.py</code>
* After the install was successful please type <code>pip install pyserial pyusb</code> followed by Enter.
* If you do not wish to install python, and would rather copy files across, the command line utility RoboCopy is recommended. For example: <code>Robocopy.exe ./my_app/ d:/apps/my_app</code>

=== OSX / Linux ===

* Python: Open a terminal and type <code>python --version</code>. If you get a version number you're good to go, otherwise go to https://www.python.org/downloads/ and download Python version 3.x. After the download is finished you can install it.
* Go to https://bootstrap.pypa.io/get-pip.py and save the file into your folder
* Use a terminal to go to the folder you created ([http://www.macworld.com/article/2042378/master-the-command-line-navigating-files-and-folders.html this is how you do it]) and type <code>python get-pip.py</code>
* Now type <code>python get-pip.py</code>
* After the install was successful please type <code>pip install pyserial pyusb</code> followed by Enter

=== Problems ===
* If you have problems install python, please use google, there are lots of good explanations out there
* For information about how to install <code>pip</code> have a look here: https://pip.pypa.io/en/stable/installing/

== 6. (Optional) Update your badge's micropython ==
'You can skip this step', but since TiLDA is still a work in progress, it's best to update regularly. So why not do it now? It's easy, just follow the instructions here: [[TiLDA_MK3/Firmware_Update]]

== 5. Run a whole file of code ==
While you can do most things via the terminal like you just did, it's a bit easier to work on a file that you can edit. So let's do that.
* Go to https://raw.githubusercontent.com/emfcamp/micropython/tilda-master/tools/pyboard.py and use your browser to save it as "pyboard.py" into your newly created folder
* Open a text editor. On Windows you can search for <code>Notepad</code>, on OSX there's one called <code>textedit</code> and if you're on Linux you can probably find one by searching for "edit".
* Copy the following and save it as <code>test.py</code> in your folder:
<source lang="python">
print(1 + 2)
</source>
* Open a terminal, navigate to the right folder (see step 5 for more info)
** Windows: <code>python pyboard.py test.py --device=/COM4</code> Replace COM4 with whatever port your badge installed as.
** OSX: type <code>python pyboard.py test.py --device=/dev/tty.usbmodem*</code>
** Linux: type <code>python pyboard.py test.py --device=/dev/ttyACM*</code>
* You should now see the your terminal showing <code>3</code>. Your getting good at this!

'''Hint''': If you don't want the home app to start every time you can create an empty <code>main.py</code> file in the USB folder. This will stop the boot from loading the home screen and allow you do run code on your badge undisturbed. But remember to "safely eject" the badge after writing the file and to remove it again when you want the normal behaviour back

== 7. Blink ==
So far all we've seen is the badge doing some maths and sending the result back via usb. Let's start with one of the simplest hardware device on the badge, a LED (which means "Light emitting diode") -- We want to make it blink.

Create a file called <code>blink.py</code> and copy this bit of code into it:

<source lang="python">
import pyb
led = pyb.LED(1)
led.on()
pyb.delay(500)
led.off()
pyb.delay(500)
led.on()
pyb.delay(500)
led.off()
pyb.delay(500)
led.on()
</source>

Save it and use a terminal to execute it (See Step 5 - but make sure to replace the filename in the command). Have a look at your badge, you should see the tiny LED labeled "A" (It's right between the B button and the screen) flash twice before and then staying on.

Now, let's see what the code actually does.

<source lang="python">
import pyb
</source>
This line tells your badge to import the "pyb" library. It allows you to do various hardware related things with your badge (the full list is [http://docs.micropython.org/en/latest/pyboard/library/pyb.html here]). This is something very important in python, you always need to import libraries before you can use them.

<source lang="python">
led = pyb.LED(1)
</source>
This line uses the pyb module we've just imported and creates a LED object. The "<code>1</code>" means we're using the first LED on the badge. Change it to "<code>2</code>", save it and run pyboard.py again - Now the LED B should flash in green.

The <code>led</code> bit before the <code>=</code> means that we're not only creating an LED object, but we're also storing it for later use.

<source lang="python">
led.on()
</source>
Here we're using the reference to the LED object we've just created and calling the <code>.on()</code> function on it. Most python objects have multiple functions you can use. In this case you can look the them up here: http://docs.micropython.org/en/latest/pyboard/library/pyb.LED.html?highlight=led

<source lang="python">
pyb.delay(500)
</source>
This line uses the <code>pyb.delay()</code> function to pause the execution of our program for a while. The <code>500</code> is a number in milliseconds and the code is stopping for half a second. We need this delay to give your eyes some time to see that the LED has turned on. Try playing with different numbers or leaving the line out altogether to get a feeling for it.

== 8. Blink forever ==
Since our original <code>blink.py</code> script is only blinking twice it might be easy to miss. Let's fix this by blinking a bit longer:

<source lang="python">
import pyb
led = pyb.LED(1)
while True:
led.toggle()
pyb.delay(500)
</source>

Be careful to make sure you're copying the spaces in front of the last two lines as well, they're very important in Python! If you want to type them you have to use the <code>Tab</code> key on your keyboard - It's normally on the left of your keyboard, two keys above the <code>Shift</code> key.

Save this code and run it via <code>pyboard.py</code> again. You should now see the red LED blinking forever. So what's happening here?

<source lang="python">
while True:
led.toggle()
pyb.delay(500)
</source>
This is called a "while loop" in Python. It means that a certain bit of code (the one indented by the Tab at the beginning of the line) will be repeated over and over again until a certain condition is not fulfilled anymore. In this case the condition is <code>True</code> which is the Python-way of saying "this is always correct". Therefore the loop will repeat forever.

<code>led.toggle()</code> is similar to <code>led.on()</code> and <code>led.off()</code>, but instead of always turning the LED on or off it switches between the states. Very useful in our case!

This kind of "infinite loop" is quite useful for a lot of badge code, but often you also want to have some way of leaving the loop. Try this instead:
<source lang="python">
import pyb
import buttons
buttons.init()
led = pyb.LED(1)
while not buttons.is_pressed("BTN_MENU"):
led.toggle()
pyb.delay(500)
</source>

There are a few new things here: First we have imported a new library called <code>buttons</code>. This library helps you with all the buttons on the badge. If you want to use buttons in your script you also have to call <code>buttons.init()</code>, so that's what we're doing in line 3.

We have also changed the <code>while</code> loop with a new statement <code>not buttons.is_pressed("BTN_MENU")</code>. Like I said above, <code>while</code> loops will go on forever while its condition is fulfilled. We have now changed the condition to be "while the MENU button is not pressed".

Try running the code. You will again get the same blinking LED, but this time you should be able to stop it by pressing the MENU button.

== 8. Hello Screen ==

Ok, now let's try to write something on the screen. TiLDA comes with a colour screen and we can use a library called UGFX to draw on it.

Create a <code>main.py</code> file and put this in there:
<source lang="python">
import ugfx
import buttons
import pyb

ugfx.init()
buttons.init()
ugfx.clear(ugfx.YELLOW)

ugfx.text(5, 5, "Hello World", ugfx.RED)
ugfx.fill_circle(100, 100, 30, ugfx.GREEN)
ugfx.fill_circle(200, 100, 30, ugfx.GREEN)
ugfx.area(80, 150, 140, 20, ugfx.GREEN)
ugfx.area(120, 170, 60, 20, ugfx.GREEN)
</source>

If you run this file you should see a the screen turn yellow with some text and a (very simple) smiley.

If you use the screen you have to make sure you're using <code>ugfx.init()</code>, otherwise nothing will work. <code>ugfx.clear()</code> is used to clear the screen (in this case with a special colour) and the next 5 lines are drawing some text and a few basic shapes.

<code>ugfx.text(x, y, text, color)</code> Prints some text at position (x, y) in a given colour. x and y are coordinates on the screen. x=0 and y=0 means the top-left of the screen and x=320 y=240 is the bottom right corner. Try changing the two numbers and see how the text moves around on the screen.

<code>ugfx.fill_circle(x, y, radius, color)</code> draws a circle on the screen.

<code>ugfx.area(x, y, width, height, color)</code> draws a rectangle on the screen.

There are more basic drawing operations. You can find a list of them here: [[TiLDA MK3/ugfx|uGFX]]

== 10. Your own app ==

Having to have your badge connected to your computer all the time is a bit boring. Let's make it an app, so you can carry it around!

Update your <code>main.py</code> to look like this:

<source lang="python">
### Author: Your Name
### Description: Smiley!
### Category: Tutorial
### License: MIT
### Appname : Smiley

import ugfx
import buttons
import pyb

ugfx.init()
buttons.init()
ugfx.clear(ugfx.YELLOW)

ugfx.text(5, 5, "Hello World", ugfx.RED)
ugfx.fill_circle(100, 100, 30, ugfx.GREEN)
ugfx.fill_circle(200, 100, 30, ugfx.GREEN)
ugfx.area(80, 150, 140, 20, ugfx.GREEN)
ugfx.area(120, 170, 60, 20, ugfx.GREEN)

while not buttons.is_pressed("BTN_MENU"):
pyb.wfi()
</source>

The bit at the top is a comment, it's not actually part of the code and python ignores it. It does however help us categorise the app. Make sure you update your name :)

Plug your badge in and open the USB drive. Go into the "apps" folder and create a new folder called "hello_screen". Copy your newly updated <code>main.py</code> into there and safely eject the device. If you now press the reset button at the back of your badge it will restart normally. Wait until your name appears and press the MENU button. Go all the way to the bottom right and select "View all". Now you have to press "right" until you find the "Smiley" app. Select it and press A - You should now see your smiley.

== 11. Publish your app to the app library ==

Now that you have your own smiley app, why not share it with others?

Find your main.py and create an archive of it. Most operating systems have something build in for that purpose. In OSX you can right click and select "Compress main.py", under Windows you can select "???" (someone please fill this) and under Linux you right click the files and use "Compress...". You should now have a new file called <code>main.zip</code> or similar.

Go to http://api.badge.emfcamp.org/ and sign up with your email address and a password. In the top right there's a field called "Create New App" - Put "Smiley" into the field next to it and then click "Create". On the next screen click the "Choose File" button and select your <code>main.zip</code>. Now press "Upload" - and you're done!

You now have to wait until we have reviewed your app to make sure it's not doing something weird and then we'll hit the "publish" button and everyone on the camp site will be able to download your newly created app to their badge. If we're not quick enough, feel free to come to the badge tent and we'll hurry the review up ;)

= Alternative ways to work with TiLDA =

All of the python code which runs on the badge can be modified on the mass storage device, and new apps can be added this way too. Be careful when using text editors to modify files on the device, if the mass storage is not 'safely removed' before removal, corruption of the file being edited can occur.

When writing your own code, it is advised edit code on your computer, then copy it across to the badge, wait for the red 'writing' LED to go out, reset it, and run.
This way you don't need to worry about safely removing the badge each time.

To interactively run code on the badge, a python REPL can be accessed via the virtual serial port. Once you have found the serial port, use your favourite serial terminal to connect to the badge. Since the badge will be running the main software, press Ctrl+c to stop it, and the badge will display '>>>' to indicate it is ready to receive commands.

The badge runs micropython, and as a result does not contain everything you may expect from full python. See the micropython docs in the lniks below for more information.
The badge has additional APIs, in particular for the LCD, Wifi and IMU, which are also listed below.

TiLDA MK3

2016-08-08T18:59:06Z

Liedra:

[[File:TiLDA_MK3_front.jpg|right|500px|TiLDA Mkπ]]

== Using your badge ==

<div style="background-color: #FFFFDD; border: 1px solid #808000; padding: 5px;"><strong>If you just got your badge and it doesn't do anything</strong>, don't despair, quite a few of them need to be [[TiLDA_MK3/reset|factory reset]] before showing the loading screen. Press and hold <code>MENU</code> while quickly pressing the reset button at the back. Keep the <code>MENU</code> button hold for another 2 seconds while the green light on the front is blinking. Release it <i>while</i> the green light is on.<br>If this doesn't work you can [[TiLDA_MK3/Firmware_Update|update the badge firmware]]. If this doesn't work, please come and join us in #tilda on [https://freenode.net/ Freenode IRC]</div>

<div style="background-color: #DDFFFF; border: 1px solid #808000; padding: 5px;">If you're having problems downloading some apps from the App Library <b>please update your badge via the App Library update option</b>. After a restart it should work much smoother.</div>

=== Assembly ===
With your badge you will receive a booklet explaining how it's done. If you have any problems, please come to the Badge Operation Center and we will help you.

=== Basic usage ===
After you have assembled your badge you can just use the tiny switch at the bottom of the screen to turn your badge on. Alternatively you can use any USB power source. If you turn your badge on for the first time (or if for some reason it has reset itself) you will get some on-screen information while we try to download the newest set of software.

If at any point you want to restart your badge you can just press the reset button at the back.

==== Changing your name ====

# Press 'Menu'
# Select the 'Change Name' app and press 'A'
# Use the joystick and 'A' key to enter your name
# Press 'Menu' to save your name and reset the badge - your name should now be displayed!

==== Installing new apps ====

# Press 'Menu'
# Select the 'App Library' app and press 'A'
# Select "Browse App Store"
# Select a category and then an app. Wait until you see the description and press "A" to save it.
# Press B a few times (or alternatively MENU) to restart your badge
# On the home screen you can now press MENU and select "View all" to find your newly installed app. If you want to pin it to the quick launcher screen select your app and press MENU. If you just want to start it press A instead.

=== WiFi ===
Your TiLDA Badge has built-in wifi support. It should all just work if you're at the campsite, but if you're on your own network you might have to tell the badge about it. For more information please have a look here: [[TiLDA MK3/wifi|WiFi]]

<strong>A word of warning</strong>: During EMF the badge will use "emf-insecure". This is, as the name implies, not the most secure way of transmitting data. On top of that there are some problems with HTTPS and SSL, so we're not using it for with the default apps (we're working on it!). Please <span style="color:red">don't send anything private or important to or from the badge via wifi</span>.

=== Charging ===
The badge charges via a microUSB socket, and takes about 2-3 hours for a full charge. The red charge LED next to the USB connector will extinguish when charging is complete

=== Nothing works! Help! ===

Don't worry, you can always "factory reset" your badge. Please follow these instructions: [[TiLDA_MK3/reset|Resetting]]

If everything else absolutely fails, you can try following these instructions (advanced): [[TiLDA_MK3/Firmware_Update]]

== Hacking your badge ==

'''[[TiLDA_MK3/Introduction_to_badge_hacking|Badge Hacking Workshop Documentation]]'''

One of the main goals of TiLDA is to make hacking it as easy as possible. All you need to do so is a computer with USB and your badge.

* '''[[TiLDA MK3/Get Started|Step-by-step: How to get started]]'''
* '''[[TiLDA MK3/Run Code|3 Ways to run code on your TiLDA]]'''
* [[TiLDA MK3/App Store Submissions|App Store Submissions]]

The badge itself runs code written in the computer language [https://en.wikipedia.org/wiki/Python_(programming_language) Python] which is run by a bit of software called [https://micropython.org/ Micropython].

For more information about the functions available please have a look at the [[#Badge API|Badge API]] section of this page.

If you're already familiar with all this you can jump right into the topic of Apps. Apps can be shared via the EMF App Library or by copying files of and on via USB. If you want to know more about how this works go to [[TiLDA MK3/apps]]

In case you're more interested in what makes the hardware tick and your confident with C++ and microprocessors then you can work directly with the micropython code that runs TiLDA: [[TiLDA MK3/build|How to build the firmware from scratch]]

All code used is hosted on Github. Contributions and PR are very welcome!
* https://github.com/emfcamp/micropython
* https://github.com/emfcamp/Mk3-Firmware
* https://github.com/emfcamp/Mk3-Server

=== Some ideas ===

[[TiLDA MK3/Ideas|Please share what you've done (or want to do) with others!]]

[https://github.com/emfcamp/Mk3-Hardware/blob/master/case-final.dxf Laser cut case files]

== Badge API ==

=== Build-in ===
* [http://docs.micropython.org/en/latest/pyboard/ documentation] - General Micropython libarary
* [[TiLDA MK3/ugfx|uGFX]] - The TiLDA LCD colour screen
* [[TiLDA MK3/documentation/cc3100|CC3100]] - The wifi chip
* [[TiLDA MK3/rtc|RTC]] (real time clock)
* [[TiLDA MK3/adc|ADC]] (analogue reading)
* [[TiLDA MK3/timer|Timer]]
* Microcontroller peripherals [https://micropython.org/doc/module/pyb/] (Timers, PWM, serial etc)

=== TiLDA Libraries ===
On top of the build-in modules above we have also created a bunch of helpful libraries written in python. If you go through the bootstrap process or use the App Library you should always have a full set of those on your badge. If for some reason this isn't the case you can download our repository from https://github.com/emfcamp/Mk3-Firmware and copy the <code>lib</code> folder onto your badge.

TBD, for now please have a look at the libraries themselves: https://github.com/emfcamp/Mk3-Firmware/tree/master/lib

* [[TiLDA MK3/lib/buttons|buttons]]
* database
* dialogs
* filesystem
* http_client
* imu
* wifi
* NTP Example: https://gist.github.com/drrk/4a17c4394f93d0f9123560af056f6f30
* On board LED "NeoPixel" example: https://github.com/mayhem/tilda-mk3-led-demo

(feel free to add additional ideas, and create links new wiki pages to on-going projects, perhaps someone will want to contribute)

== Badge hardware ==
TiLDA comes with a long list of very useful hardware. Some might be obvious, but some are a bit hidden.
* Colour LCD screen 320x240
* Joystick and A/B/Menu Buttons
* Wifi (cc3100)
* Accelerometer
* Compass
* Buzzer
* Battery
* <s>WS2812B aka "Neo Pixel"</s> on port PB13. [https://badge.emfcamp.org/wiki/TiLDA_MK3/How_to_fix_NeoPixel Sadly defunct]
* MicroSD slot

NOTE: The WS2812B is actually on pin PB13, not X2 as shown below!

[[File:pinout-1.png | 500px]] [[File:pinout2-1.png | 500px]]

User:Liedra

2016-08-08T18:52:19Z

Liedra: Created page with "Hi! I am blindly hacking my way through all of this stuff and try to make things easier for newbies."

Hi!

I am blindly hacking my way through all of this stuff and try to make things easier for newbies.

TiLDA MK3/Firmware Update

2016-08-08T18:32:55Z

Liedra:

TiLDA MK3/Firmware Update

2016-08-08T18:31:09Z

Liedra: Created page with " == Update your Tilda Mk3== This websites will help you to update your Tilda Mk3 badge. But be careful, following these instructions will delete all files and setting on yo..."

TiLDA MK3

2016-08-08T18:21:02Z

Liedra: /* Nothing works! Help! */

[[File:TiLDA_MK3_front.jpg|right|500px|TiLDA Mkπ]]

== Using your badge ==

<div style="background-color: #FFFFDD; border: 1px solid #808000; padding: 5px;"><strong>If you just got your badge and it doesn't do anything</strong>, don't despair, quite a few of them need to be [[TiLDA_MK3/reset|factory reset]] before showing the loading screen. Press and hold <code>MENU</code> while quickly pressing the reset button at the back. Keep the <code>MENU</code> button hold for another 2 seconds while the green light on the front is blinking. Release it <i>while</i> the green light is on.<br>If this doesn't work you can [https://update.badge.emfcamp.org/ update the badge firmware]. If this doesn't work, please come and see us at the badge tent</div>

<div style="background-color: #DDFFFF; border: 1px solid #808000; padding: 5px;">If you're having problems downloading some apps from the App Library <b>please update your badge via the App Library update option</b>. After a restart it should work much smoother.</div>

=== Assembly ===
With your badge you will receive a booklet explaining how it's done. If you have any problems, please come to the Badge Operation Center and we will help you.

=== Basic usage ===
After you have assembled your badge you can just use the tiny switch at the bottom of the screen to turn your badge on. Alternatively you can use any USB power source. If you turn your badge on for the first time (or if for some reason it has reset itself) you will get some on-screen information while we try to download the newest set of software.

If at any point you want to restart your badge you can just press the reset button at the back.

==== Changing your name ====

# Press 'Menu'
# Select the 'Change Name' app and press 'A'
# Use the joystick and 'A' key to enter your name
# Press 'Menu' to save your name and reset the badge - your name should now be displayed!

==== Installing new apps ====

# Press 'Menu'
# Select the 'App Library' app and press 'A'
# Select "Browse App Store"
# Select a category and then an app. Wait until you see the description and press "A" to save it.
# Press B a few times (or alternatively MENU) to restart your badge
# On the home screen you can now press MENU and select "View all" to find your newly installed app. If you want to pin it to the quick launcher screen select your app and press MENU. If you just want to start it press A instead.

=== WiFi ===
Your TiLDA Badge has built-in wifi support. It should all just work if you're at the campsite, but if you're on your own network you might have to tell the badge about it. For more information please have a look here: [[TiLDA MK3/wifi|WiFi]]

<strong>A word of warning</strong>: During EMF the badge will use "emf-insecure". This is, as the name implies, not the most secure way of transmitting data. On top of that there are some problems with HTTPS and SSL, so we're not using it for with the default apps (we're working on it!). Please <span style="color:red">don't send anything private or important to or from the badge via wifi</span>.

=== Charging ===
The badge charges via a microUSB socket, and takes about 2-3 hours for a full charge. The red charge LED next to the USB connector will extinguish when charging is complete

=== Nothing works! Help! ===

Don't worry, you can always "factory reset" your badge. Please follow these instructions: [[TiLDA_MK3/reset|Resetting]]

If everything else absolutely fails, you can try following these instructions (advanced): [[TiLDA_MK3/Firmware_Update]]

== Hacking your badge ==

'''[[TiLDA_MK3/Introduction_to_badge_hacking|Badge Hacking Workshop Documentation]]'''

One of the main goals of TiLDA is to make hacking it as easy as possible. All you need to do so is a computer with USB and your badge.

* '''[[TiLDA MK3/Get Started|Step-by-step: How to get started]]'''
* '''[[TiLDA MK3/Run Code|3 Ways to run code on your TiLDA]]'''
* [[TiLDA MK3/App Store Submissions|App Store Submissions]]

The badge itself runs code written in the computer language [https://en.wikipedia.org/wiki/Python_(programming_language) Python] which is run by a bit of software called [https://micropython.org/ Micropython].

For more information about the functions available please have a look at the [[#Badge API|Badge API]] section of this page.

If you're already familiar with all this you can jump right into the topic of Apps. Apps can be shared via the EMF App Library or by copying files of and on via USB. If you want to know more about how this works go to [[TiLDA MK3/apps]]

In case you're more interested in what makes the hardware tick and your confident with C++ and microprocessors then you can work directly with the micropython code that runs TiLDA: [[TiLDA MK3/build|How to build the firmware from scratch]]

All code used is hosted on Github. Contributions and PR are very welcome!
* https://github.com/emfcamp/micropython
* https://github.com/emfcamp/Mk3-Firmware
* https://github.com/emfcamp/Mk3-Server

=== Some ideas ===

[[TiLDA MK3/Ideas|Please share what you've done (or want to do) with others!]]

[https://github.com/emfcamp/Mk3-Hardware/blob/master/case-final.dxf Laser cut case files]

== Badge API ==

=== Build-in ===
* [http://docs.micropython.org/en/latest/pyboard/ documentation] - General Micropython libarary
* [[TiLDA MK3/ugfx|uGFX]] - The TiLDA LCD colour screen
* [[TiLDA MK3/documentation/cc3100|CC3100]] - The wifi chip
* [[TiLDA MK3/rtc|RTC]] (real time clock)
* [[TiLDA MK3/adc|ADC]] (analogue reading)
* [[TiLDA MK3/timer|Timer]]
* Microcontroller peripherals [https://micropython.org/doc/module/pyb/] (Timers, PWM, serial etc)

=== TiLDA Libraries ===
On top of the build-in modules above we have also created a bunch of helpful libraries written in python. If you go through the bootstrap process or use the App Library you should always have a full set of those on your badge. If for some reason this isn't the case you can download our repository from https://github.com/emfcamp/Mk3-Firmware and copy the <code>lib</code> folder onto your badge.

TBD, for now please have a look at the libraries themselves: https://github.com/emfcamp/Mk3-Firmware/tree/master/lib

* [[TiLDA MK3/lib/buttons|buttons]]
* database
* dialogs
* filesystem
* http_client
* imu
* wifi
* NTP Example: https://gist.github.com/drrk/4a17c4394f93d0f9123560af056f6f30
* On board LED "NeoPixel" example: https://github.com/mayhem/tilda-mk3-led-demo

(feel free to add additional ideas, and create links new wiki pages to on-going projects, perhaps someone will want to contribute)

== Badge hardware ==
TiLDA comes with a long list of very useful hardware. Some might be obvious, but some are a bit hidden.
* Colour LCD screen 320x240
* Joystick and A/B/Menu Buttons
* Wifi (cc3100)
* Accelerometer
* Compass
* Buzzer
* Battery
* <s>WS2812B aka "Neo Pixel"</s> on port PB13. [https://badge.emfcamp.org/wiki/TiLDA_MK3/How_to_fix_NeoPixel Sadly defunct]
* MicroSD slot

NOTE: The WS2812B is actually on pin PB13, not X2 as shown below!

[[File:pinout-1.png | 500px]] [[File:pinout2-1.png | 500px]]