Programming the LilyMini

Pages
Contributors: MikeGrusin, Gella
Favorited Favorite 2

Introduction

The LilyMini is a tiny sewable computer that you can use to make interactive craft projects. The LilyMini is part of the LilyPad line - a unique collection of electronic parts designed to be connected together with conductive thread instead of wire. The LilyMini comes pre-programmed to blink LEDs in fun ways, but you can also write your own programs using the popular (and free!) Arduino system. It’s easy, we’ll show you how!

In this tutorial, we’ll set up the Arduino software to program the LilyMini. The process is the same whether you are using a standalone LilyMini (Coming Soon!) or the LilyMini ProtoSnap.

Once you’ve set up Arduino using the instructions in this tutorial, you’ll be able to write and upload your own programs to the LilyMini.

alt text

Suggested Reading

Setting Up Arduino

When you first install the Arduino software, it knows how to program a number of “standard” Arduino-compatible boards. You can add the LilyMini to this list by following the three steps below. You’ll need to do these steps on every machine you want to use to program LilyMini, but once it’s done, it won’t need to be done again.

BETA SOFTWARE ALERT! We've been working hard to add LilyMini programming support to Arduino. The instructions below will let you test what we have so far, but we're still chasing down some bugs. The basics work (digital out, digital in, analog in, and serial monitor), but other features are in progress and may not work correctly (yet). We're providing these instructions for those who want to try out LilyMini programming as soon as possible. These instructions will be updated as we fix bugs and add features. (And if you have fixes for us, by all means let us know!)

The LilyMini extensions currently work on Mac and Windows 10 systems. Linux support is untested. We are actively working on support for earlier versions of Windows.

Update Arduino! LilyMini will only work with Arduino version 1.8 or higher. Please install (or update to) the latest version of Arduino before installing the LilyMini software.

If this is your first time using Arduino, you can install it by following our Installing the Arduino IDE tutorial.

Connect to the Internet! You'll need to be connected to the internet to install the LilyMini software.

Beta Testers: If you've been helping us out with beta testing (thank you!), you'll need to delete the earlier SparkFun SAMD Boards entry from Board Manager, delete the beta testing URL from preferences, restart Arduino, and continue with the steps below.

Ready? Let’s get started!

1. Add Sparkfun to your Preferences

Start the Arduino software (version 1.8 or higher) and open the Preferences window by choosing File > Preferences from the menu.

Now copy the below text and paste it into the “Additional Boards Manager URLs” text box:

https://raw.githubusercontent.com/sparkfun/Arduino_Boards/master/IDE_Board_Manager/package_sparkfun_index.json

alt text

No room? If there is already a URL in the box, click the button to the right of the box. This will open a window allowing you to paste the URL onto a new line. (Beta testers should delete previous Sparkfun URLs.)

When you’re done, click the “OK” button.

2. Install Arduino SAMD Boards

We’ll now install two Arduino extensions. The first allows Arduino to compile code for “SAMD” processors (which the LilyMini uses), and the second one will add the LilyMini specifically.

Start up Arduino, and open the Boards Manager window by choosing Tools > Board > Boards Manager… (The Boards Manager option is at the very top of the list of boards; you may need to scroll up to see it.)

alt text

When the Boards Manager window opens, it will present a long list of options. Type “samd” (without quotes) into the “Filter your search” box at the top of the window. This will shrink the list down to the options with “samd” in them.

alt text

You should see two (or more) entries, including Arduino SAMD Boards and SparkFun SAMD Boards. We’ll install both of these, starting with Arduino SAMD Boards.

Order counts! Though you'll be installing both "SAMD" entries, be sure to install the Arduino SAMD Boards entry FIRST.
Troubleshooting: If you don't see a SparkFun entry, double check that you did step one properly and that you're connected to the internet. You might also try closing and restarting the Arduino software.

Click anywhere in the Arduino SAMD Boards box. A version number and an “Install” button will appear. Click the install button. This will download and install the extension. This extension is quite large and will take a while to install. It may also ask for permission to install drivers; please let it do so.

alt text

If everything worked, a blue “INSTALLED” should appear next to the Arduino SAMD Boards title.

3. Install SparkFun SAMD Boards

When the Arduino SAMD Boards has finished installing, click anywhere in the SparkFun SAMD Boards box. A version number and an “Install” button will appear.

BEFORE CLICKING "INSTALL" CHOOSE VERSION 1.4.0 FROM THE DROPDOWN MENU. Later versions do not include the LilyMini downloading tool.

Once you’ve selected 1.4.0 from the version list, click the install button. This package is small and will install much faster than the Arduino SAMD Boards.

alt text

If everything worked, a blue “INSTALLED” should appear next to the SparkFun SAMD Boards title. Congratulations, you’re done installing the LilyMini extensions!

Uploading Code

Once you’ve installed the LilyMini extensions to Arduino, you’re ready to start programming the LilyMini!

Note that you won’t have to install the LilyMini extensions again (whew!), but you will need to perform the below three steps every time you want to program the LilyMini. These three steps are:

  1. Connect the LilyMini to your computer (and turn it on)
  2. Select the board type (LilyMini)
  3. Select the port

Don’t worry, Arduino will remember these things so you’ll usually just need to double-check that the settings are correct. It will all become second nature soon.

Let’s go over the three steps in detail:

1. Connect the LilyMini to your Computer (and turn it on)

Connect the LilyMini to a USB port on your computer using a micro USB cable. The cable can only be inserted one way, and should snap down securely.

TIP: Both the micro-USB cable and the connector on the LilyMini have a subtle "D" shape to them. Match this shape to plug it in properly.

Here’s something important to remember: The LilyMini must be powered up in order to program it. If you plug it in and the built-in LED doesn’t fade up from black to green, press the “ON” button to wake it up. (You’ll know it’s powered up if it appears in Arduino’s port list, which we’ll talk about below.)

The LilyMini can be powered by a coin cell, or USB cable, or both at the same time. It’s perfectly safe to have a coin cell in the LilyMini while it’s attached to your computer via USB.

2. Select LilyMini from the Board Menu

Once the LilyMini software is installed, it will be available in the Tools > Board list. Go there now and select LilyPad LilyMini. Depending on how many boards are already in the list, you may need to scroll down to get to it.

alt text

Troubleshooting: If you don't see "LilyPad LilyMini" in the board list, go back to Setting Up Arduino and double-check that you performed all the steps.

3. Select the Port

Whenever you plug a USB device into your computer, your computer will assign it a port number. On Windows these are listed as COM##; on a Mac or Linux machine they will be “/dev/cu.usbmodem####”.

Arduino needs to know which port your LilyMini is attached to so it can program it. This used to be difficult to determine, but the LilyMini has a handy feature that identifies itself. Go to the Tools > Port menu, and select the port that has “LilyPad LilyMini” next to it. Easy!

alt text

TROUBLESHOOTING: If you don't see a port with "LilyPad LilyMini" next to it, ensure that the LilyMini is powered up, and that the USB cable is securely connected to both the LilyMini and your computer. Also, cables go bad, and some micro-USB cables are only meant for charging and don't pass data - they'll power the LilyMini, but it won't show up in the port menu. Try a different cable. And if all else fails, see "Recovery Mode" below.

Uploading Code

To review, once you’ve:

  1. Connected the LilyMini to your computer (and turned it on)
  2. Selected the board type (LilyMini)
  3. Selected the port

you’re ready to upload code! Let’s test everything out:

Load the “blink” example from the menu File > Examples > 01.Basics > Blink, and click the “Upload” button (the large round button with the right arrow in it).

Arduino will compile the code, then send it to the LilyMini via USB. While the code is uploading, the LilyMini’s built-in RGB LED will blink various colors, and when the code finally runs, the red LED will slowly blink. Success!

If this all works, congratulations! You’re all set up and ready to program the LilyMini. But before you go, please read the “Recovery Mode” section below so you know how to recover from a bad upload.

If something didn’t work, follow the troubleshooting steps below (coming soon).

Recovery Mode

Most of the time, code uploads will work perfectly.* But occasionally an upload will fail halfway through. In this case, the LilyMini will try to run the the bad code, run out of instructions, and lock up. While it’s locked up, the USB won’t work, so you won’t be able to upload new code to fix it. Power cycling won’t help because it will just run the bad code again. The board will seem dead! HELP!

To recover from this problem, the LilyMini has a recovery mode built into it. If you hold down the “ON” button while powering it up, the LilyMini won’t run any uploaded code (good or bad). It will quietly wait for a USB connection, which will then let you upload new code to it.

The exact steps to get into recovery mode are:

  1. Unplug the LilyMini from any USB cables, and remove the coin cell if one is installed. The LilyMini must be completely powered down for this to work.

  2. Plug a micro USB cable into your computer, but don’t plug the other end into the LilyMini yet.

  3. Hold down the “ON” button on the LilyMini.

  4. While you’re holding down the “ON” button, plug the USB cable into the LilyMini. Once the RGB LED turns on, you can release the “ON” button.

  5. The LilyMini’s RGB LED will turn blue as it powers up in Recovery Mode, then green as it establishes a USB connection with your computer. The LilyMini should now appear in Arduino’s port list, and you can upload new code to it.

Remember this tip! You can use it to bring “dead” LilyMinis back to life.

* "Upload Failed?" The SAMD tools are new and still a little buggy. Occasionally Arduino will falsely report that the upload failed, even though it uploaded and ran fine. If you can still see your LilyMini in the Arduino port list, everything's fine. You'll be able to upload new code to it normally. You'll only need to enter Recovery Mode if the LilyMini ever disappears from the port list.

Programming Notes

If this is your first time programming, you’re in for some fun! We recommend you head over to the LilyMini Programming Guide (COMING SOON) which will walk you through simple programming lessons that you can also use in your projects.

If you’ve already programmed Arduino for a while, read on for tips about the LilyMini. It’s very similar to other Arduinos, but has some special features and limitations you’ll want to know about.

Code Space

To keep the cost as low as possible, the LilyMini uses an inexpensive SAMD11 processor. This processor does not provide a lot of programming space (after the Arduino “core” is loaded you’ll have about 4KB free), but that’s more than enough for the short sketches typically used by beginning programmers. You can pack a lot of simple code into the LilyMini, but we suggest you avoid libraries and floating-point math as you can quickly run out of space.

Pin Numbering

The LilyMini’s I/O pins have been renumbered to simplify things for beginners. The external sewtabs are numbered 1-4 (unlike other Arduinos there is no pin “0”), and the internal RGB LED is numbered 5-7 (R,G,B respectively). All external sewtabs will work for digital in, digital out, analog in, and analog out*. Pin 13 (which doesn’t physically exist on the LilyMini) and “LED_BUILTIN” (Introduced in Arduino 1.8) are tied to the built-in red LED to maintain compatibility with existing example code.

* As of this writing, analog out is working on the external sewtabs, but not the internal RGB LED.

The following names are predefined in the core if you prefer using names rather than pin numbers:

LED_RED     = 5
LED_GREEN   = 6
LED_BLUE    = 7
LED_BUILTIN = 5 // Introduced in Arduino 1.8, tied to red LED

Analog Input

All four external sewtabs support analog input. The core has been hardcoded to 10 bits (0 to 1023) for compatibility with existing sketches. Several “virtual” pins are predefined for battery voltage, 1-volt reference, and temperature. Because analogRead() can fluctuate with changing battery voltage, functions have been provided to measure true volts from any pin or the battery. (To avoid floating-point numbers that require a lot of space, these return integers that are 100x the floating-point value.)

// Virtual "pins" for analogRead()
PIN_BATT    // Battery voltage (when not on USB)
PIN_1V      // 1 volt reference
PIN_TEMP    // Temperature sensor (internal to SAMD11)

// True voltage-reading macros, these return e.g. 199 for 1.99V
int analogReadVolts(pin)    // Read true voltage on any sew tab
int analogReadBattVolts()   // Read true voltage of the battery (if not on USB)

Serial Monitor

The serial monitor on the LilyMini is slightly different than other Arduinos in that activating it does not reset the processor. This means that if your sketch is already running and you activate the serial monitor, you’ll see output from that point forward, but will miss whatever it may have output in the past. If you need to see serial output from the beginning of your sketch, you can keep the serial window open, or put the following statement at the end of your setup():

while (!Serial) ;

This will wait (forever if necessary) until the serial monitor window is activated before continuing.

ProtoSnap Example Code

To go along with the Intro to Arduino with LilyMini ProtoSnap guide that we’re working on (coming soon), we’ve preinstalled programming examples in the Arduino IDE. To get to them, select File > Examples > LilyMini_Guide. We’ll be adding to these examples as we finish the Guide.

alt text

Resources and Going Further

If you’ve never programmed before, the Intro to Arduino with LilyMini ProtoSnap is a great place to start. It walks you through a number of simple programs that teach you how to use the LilyMini in your own projects.