TiLDA MK3/Get Started

From EMF Badge
Jump to navigation Jump to search

Get started

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

If something goes wrong, the badge can be 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. 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 Terminal followed by Enter. A white terminal window should appear.
  • type /dev/tty.usbmodem* (The * is important, so don't let it out) and hit enter
  • You should now be greeted by a line saying "Micropython"

Linux

  • Open a terminal and type screen /dev/ttyACM0
  • You should now be greeted by a line saying "Micropython"

What to do if this step doesn't work?

4. Your first line of Micropython

  • In your terminal (next to the >>>) type print(1 + 1) followed by Enter
  • You should see 2 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.

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 python get-pip.py
  • After the install was successful please type pip install pyserial pyusb followed by Enter

OSX / Linux

  • Python: Open a terminal and type python --version. 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 (this is how you do it) and type python get-pip.py
  • Now type python get-pip.py
  • After the install was successful please type pip install pyserial pyusb followed by Enter

Problems

6. (Optional) Update your badge

'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 on https://update.badge.emfcamp.org.

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. 

print(1 + 2)
  • Open a terminal, navigate to the right folder (see step 5 for more info)
    • Windows: ToDo
    • OSX: type python pyboard.py test.py --device=/dev/tty.usbmodem*
    • Linux: type python pyboard.py test.py --device=/dev/ttyACM*
  • You should now see the your terminal showing 3. Your getting good at this!

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 blink.py and copy this bit of code into it: 

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()

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. 

import pyb

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 here). This is something very important in python, you always need to import libraries before you can use them. 

led = pyb.LED(1)

This line uses the pyb module we've just imported and creates a LED object. The "1" means we're using the first LED on the badge. Change it to "2", save it and run pyboard.py again - Now the LED B should flash in green.

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

led.on()

Here we're using the reference to the LED object we've just created and calling the .on() 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 

pyb.delay(500)

This line uses the pyb.delay() function to pause the execution of our program for a while. The 500 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 blink.py script is only blinking twice it might be easy to miss. Let's fix this by blinking a bit longer: 

import pyb
led = pyb.LED(1)
while True:
	led.toggle()
	pyb.delay(500)

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 Tab key on your keyboard - It's normally on the left of your keyboard, two keys above the Shift key.

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

while True:
	led.toggle()
	pyb.delay(500)

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 True which is the Python-way of saying "this is always correct". Therefore the loop will repeat forever.

led.toggle() is similar to led.on() and led.off(), 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: 

import pyb
import buttons
buttons.init()
led = pyb.LED(1)
while not buttons.is_pressed("BTN_MENU"):
	led.toggle()
	pyb.delay(500)

There are a few new things here: First we have imported a new library called buttons. 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 buttons.init(), so that's what we're doing in line 3.

We have also changed the while loop with a new statement not buttons.is_pressed("BTN_MENU"). Like I said above, while 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

ToDo: Hello world on the screen

10. Your own app

ToDo: How to put your app to your badge and how to start it

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.

Retrieved from "https://badge.emfcamp.org/w/index.php?title=TiLDA_MK3/Get_Started&oldid=113"