Getting started with Jaluino

Author: Sebastien Lelong | Jaluino Group



Step-by-step guidelines to get started with Jaluino board

Downloading and installing Jaluino, blinking a LED, choosing a bootloader. Version 0.12.

This is the online HTML version of "Getting Started with Jaluino" PDF version. You can also download the PDF version from Jallib download section, where you'll also find all Jaluino packages.

The Jaluino Team

File attachments: 

Introduction

The following guide is here to hopefully assist you in getting started with Jaluino board. Jaluino is made of two major ingredients:
  1. hardware : Jaluino is an electronic board, an Arduino-like board, based on Microchip PIC 18F4550, on which you can plug several daughter board named "shields"
  2. software: Jaluino is also an IDE (Integrated Developement Environment), uses jalv2 high level language, jallib libraries and provides sample programs

This Getting Started document is about how to setup both these parts to get a fully functionnal platform, ready to have fun with.

Because Jaluino is opened, you'll sometime have to make choices. You'll find enough information to make appropriate decisions, according to what you need, what you have, what you can and "mood-of-the-day".

Prerequisites

Before sweetly diving into Jaluino, you first have to:

  1. find a Jaluino board: either you'll have to build it from scratch, or you can also order a PCB. Please go to Jaluino shop for more. You don't necessarily need any shield, but having at least a Crumboard shield with a breadboard can help, as it is specifically designed to help you follow some tutorials and prototype simple designs.
  2. have access to a PIC programmer: in the process of getting started, we'll soon choose and program onboard PIC 18F4550 microcontroller, with a bootloader. In order to do this, you'll need a PIC programmer, at least once. You have plenty programmers out there, like PICKit 2, Wisp648, etc... You can even build your own for free.
  3. get few parts: a LED and a resistor (1K for instance). This will be the climax of this guide, the ultimate goal to reach, that is, "Blink A LED" !
  4. power on a computer: either a PC under Windows, Mac OSX or Linux. Depending on selected bootloader, a RS-232 serial port will be needed. Either find a PC with a DB-9 serial connector, or use a USB-to-serial converter.

Once you're ready, take a deep breath.

Let's go...

Installation

Downloading Jaluino

As a first step, you'll need to download latest Jaluino archive. You can retrieve it from Jaluino Google Code download section. Actual installation is rather easy: just unzip the archive.

Figure 1. Typical Jaluino archive content

Beside usual licenses and readme files, you'll find every content related to Jaluino mainboard and shields, in order for you to manufacture them, and refer to schematics and diagrams as needed. bin contains jalv2 compiler binaries (for each platform) and several wrapper scripts, or helpers, that hopefully simplify every day tasks. lib and samples contains jalv2 libraries (mostly based on jallib) and jaluino samples, ready to compile and program. bootloaders is where you'll soon choose the program (HEX file) to upload to your Jaluino board. doc is the first place you should search when looking for a specific Jaluino information, and ide contains JaluinoIDE and other several related plugins you can install in order to setup a fully functional programming environment. Other locations are rarely used for every day usage.

Note: you can also get Jaluino from sources, accessing Google Code SVN repository. This can be useful when you want to access lastest librairies and others related tools. Content looks the same, there are few differences regarding libraries and documentation though. All in all, you should get your feet on the ground easily. Retrieving Jaluino from SVN can be done following instructions detailed in this page: http://code.google.com/p/jaluino/source/checkout.
Note: third party programs are located into 3rdparty directory, under their own licenses. Jaluino licenses obviously don't apply to them.

Installing Jaluino IDE dependencies

Jaluino project comes with an IDE, an Integrated Development Environment. This IDE, JaluinoIDE, is here to help you, by providing default commands to compile and upload your programs. It also provides features like a code browser, code completion, calltips, ... It can be used as a generic Jalv2 IDE.

  1. JaluinoIDE is based on Editra, and it's actually an Editra plugin. Editra is a cross-platform IDE, running under Windows, OSX and Linux. First download Editra, and follow guidelines regarding OS used, described on this page: http://editra.org/installation_guide. Windows installer is a binary distribution containing every Editra's dependencies, like wxPython. Under Linux, running Editra may require you to install wxPython, but nowadays, it is becoming more and more popular, it wouldn't be surprising you wouldn't have to.
    Important: JaluinoIDE requires at least Editra 0.5.51. Don't use a older version, it just won't work !
  2. Several scripts used by JaluinoIDE are based on python. It's now time to install python. Go to http://python.org, and download python1.

    • for Windows users, download python 2.5
    • for others, download either python 2.5 or 2.6
  3. You'll sure need to access Jaluino through a serial link, either with a programmer or a bootloader. You need to install pyserial, available from http://pyserial.sourceforge.net/. Windows users need to install pyserial for python 2.5, others will choose version following installed python version.

Installing Jaluino IDE

Once dependencies are installed, you can safely install Jaluino IDE. JaluinoIDE will be installed and deployed in several Editra's directories, so Editra can detect it and enable it. Since Editra is cross-platform, you can use it under Windows, OSX and Linux.

  1. As a first step, if not already done, run Editra once, so default directories will be created
    • Windows: click on Editra icon
    • Linux: type Editra in a terminal
    • OSX: probably click on Editra icon2

    You should get a window like this:

    Figure 2. Editra IDE

  2. Now close Editra, and go back to Jaluino directory. Run installation script:
    • Windows: double-click on install.py file
    • Linux: type python install.py within Jaluino directory
    • OSX: double-click on install.py
    Figure 3. Installation script opens a terminal and talks a little about it does

    Installation script copied several files to Editra, like plugins and configuration files. It also detect several parameters specific to your system, like where Jaluino has been unzipped, Editra installed, path to your python installation, etc... Should you change a parameter you can safely run this script again.

  3. Now open Editra again. So far nothing has happened, go to the Tools, open Plugin Manager and Enable Jaluino IDE plugin.
    Figure 4. Editra's Plugin Manager lists all available plugins, including JaluinoIDE previously installed
  4. Close Plugin Manager window, and restart Editra as stated. I swear this is the last time :). You should now see a Jaluino menu entry. Content is grayed, this is normal as we did not open a jalv2 file yet.
    Figure 5. "Jaluino" menu entry, JaluinoIDE plugin is correctly installed !

  5. Now go to View, Shelf and enable Jaluino shelf. This opens a window on the bottom part of Editra. This is where you'll mostly operate when compiling and uploading program.
    Figure 6. JaluinoIDE shelf. Compilation and upload output will be displayed in this window.

  6. As a final check, open jaluino_medium_blink.jal sample, which can be found in samples directory. Select "Jaluino without bootloader" in Compile's dropdown list and click on Compile icon on the right. Check there's no error in output window.
    Figure 7. Compiling our first sample


Configuring JaluinoIDE

JaluinoIDE requires you to specify information about serial link. Click on "Settings" icon (top left of Jaluino shelf) or navigate to "Jaluino" => "Settings" menu, then click on "Serial/USB" tab.

Figure 8. Serial configuration tab

Specify which port you'll use to program Jaluino, either with TinyBootloader or a programmer. You can also enter your own port on the text box. This is useful for Linux users for instance, when using a USB-to-serial adapter. In this case, you'd typically enter "/dev/ttyUSB0".

Also specify which baudrate is used. Usually 115200 when using default Jaluino files.

Congratulations ! You've just installed a fully functional Jaluino development environment3. It's now time to have fun with Jaluino board.

1 Editra for Windows, when installed from binaries (most of the time), is using python 2.5. Installing another version, like python 2.6, is possible, but installation procedure gets more complicated, particularly when installing dependency like pyserial.
2 I don't have access to an OSX box around there, so I'm not able to to test. If you're a lucky OSX owner, please report so this documentation will be completed as needed.
3 Jaluino comes with JaluinoIDE, where environment is automatically configured, as much as possible. Of course, you're free to use any other IDE, like JalEdit (http://jal.sunish.net/jaledit). Or even no IDE at all, if you're a commandline guy. If so, please report and share how you configured it, so this document can grow and let users choose different alternatives. That said, Jaluino documentation is based on JaluinoIDE, some functionalities may not be available in other IDEs.

Blink a LED

So far so good, you've been able to setup your Jaluino environment, let's now dive into this "Blink a LED" experiment. This will ensure your Jaluino board is working properly. At least to blink a LED...

How do you say "Hello" ?

Blinking a LED is somewhat the equivalent of a "Hello World" example, if you're familiar with software computing and programming language. "Hellow World" is supposed to be the simplest program, ever, which basically prints "Hello World", claiming to the whole world it's alive.

Printing something on a screen with a microcontroller isn't that simple.

In microcontrollers world, there's also a hardware part. So this "Hello World" example also has to be very simple on that side too. Blinking a LED seems to fit both hardware and software requirements of simplicity: not much parts, easy to build, easy to program, easy to check. Claiming to the world it's alive isn't as explicit as printing "Hello World" but watching a blinking LED should be enough.

Careful though: even blinking a LED can be a hair-pulling generator1. I hope you'll find enough information to pass this exam without getting bald.

Hardware setup

You have two options here:
  • Option 1: use a breadboard and connect parts to Jaluino with wires
  • Option 2: use Crumboard shield and plug it over Jaluino board

Option 1 will require several parts:

  • a breadboard
  • a LED, a red one is good
  • a resistor, from 330 to 1K

Basically, as simple as it can be, we'll plug a LED and a resistor to one of PIC outputs, as shown in the following schematic2.

Figure 1. Blinking a LED.

When assembling Jaluino and all these components on a breadboard, you should get something like this:

Figure 2. Option 1: blinking a LED, assembling the whole using a breadboard

Double check LED pin layout, be sure it's not inverted. Longest pin is the anode, it must be connected to pin RA0. Pin on the flat side is the cathode, it must be connected to the ground.

As option 2, if you're a lucky Crumboard shield owner, you can simply plug it over Jaluino and enable LEDs by putting jumpers on JP1 and JP2. You'll get two blinking LEDs for the same price...

Figure 3. Option 2: blinking two LEDs, using Crumboard shield

1 Have you correctly inserted the LED, respecting pin layout ? Do you know your LED as a working one ? Are you sure ? What about your board ? Any bad contacts ? Any power supply issue ? Was your program correctly uploaded ? Did you compile and upload the correct sample ? Did you forget to setup pin direction as output ? Does it blink too fast ? Too slow ? Irregularly ? Does it blink only when you touch the board ? Do you have to switch off lights in the room to make it blink ? Switch on ? Is your LED on strike ? Do you think you're victim of sabotage from your wife ? Worse, your cat ? Are you tired trying to make this LED blink for five hours ? Do you badly need a drink ?...
2 Schematic only shows relevant components for this experiment. Full Jaluino schematic is available at http://www.justanotherlanguage.org/content/jaluino/user_guide/jaluino_medium_schematics
3 and because this is the one I have...
4 If you're using another programmer, you can share your knowledge and post detailed instructions to the Jaluino Group, in order to improve this documentation.
5 We're actually using a modified version of original xwisp program. This modified version removes Windows specific dependencies and improve parameters handling. Don't use original version, you may face troubles.

Bootloaders

What is a bootloader ? Why do I need it ?

A bootloader is a PIC program used to upload code directly to the PIC memory, without having to deal with a PIC programmer.

A bootloader lives in microcontroller's memory. When powered, it is launched and it tries to contact a host, typically a PC host, and gets some code. This code is then recorded to PIC program memory. The way bootloader reaches host is typically through a serial link or USB.

This implies several requirements:
  • PIC must be self-writable (self-programming): it must be able to write some code into its own memory while running
  • PIC must handle serial or USB communications
  • there should be enough memory to write user program

When using a bootloader, there's actually two programs within your PIC: the bootloader itself and user's program. So, how does the PIC knows which to run ? Usually, bootloader lives near the end of PIC memory. User program, when compiled, adds a special instruction which tells the PIC to jump to bootloader program. This instruction is executed at the very beginning1. When bootloader is launched, it waits for some instructions coming from PC host. This is where user's program is sent, bootloader writing bytes of code at the beginning of memory. If no instructions was received for a given amount of time, it timeouts and jump back to the beginning of PIC memory. User's program is executed.

Why do you need this anyway ? There's no actual need, you can safely skip this part and continue to use PIC programmers. Some even prefer this way, as there are common pitfalls when using bootloaders, pitfalls you may face some day or another... So, does it worth it ?

Using a bootloader can simplify your life. For instance, you may not always have your PIC programmer around, you may not even own one. You may have access to a programmer, at a friend's or your robotic club's. Will you have to go there every time you need to program your PIC ? And possibly loose friends ?... You'd better want to program a bootloader once, then go back home and safely have fun by programming your PIC using your serial port or USB.

In addition, as there's no need for high voltage programming, as when using a PIC programmer, there's no need for yet another power supply. Programming is easier, and usually also faster (programmers can be slow). And because bootloaders use common communication links, you could be able to program your PIC through the air, using for instance a bluetooth-to-serial adapter.

How to choose a bootloader ?

There are plenty bootloaders, if you ask Google, you'd be amazed. Jaluino Medium, 18F4550 based, probably can use many out there, but comes with two bootloaders, having their own specificities:
  • Tiny Bootloader: this is a famous one, probably because it claims to be the smallest (less than 100 words, or 200 bytes), leaving plenty of space for user's program. Tinybld uses a serial link to communicate with PC host, you'll thus need to have a proper serial module connected to Jaluino. One interesting feature is it can reset PIC using RTS line. You don't even have to press reset button to get your PIC programmed, making programming cycles really fast.
  • PDFUSB bootloader: coming from Microchip PICDEM FS USB board, this one uses USB connection. No need for a serial module. It is also much bigger, closed to 2KB. While this sounds really heavy, remember you'll still have 30KB memory remaining. This is usually enough... This bootloader has been implemented by Albert Faber, using jalv2 and jallib. This is a 100% Jal bootloader! When launched, bootloader identifies itself to PC host, using USB protocol

Jaluino comes with bootloaders' sources, in case you need to modify them. This is an ASM file (PIC assembler) for Tinybld, and a Jal file for PDFUSB.

Which one to choose ? There's no definite answer, you may need to switch between both, depending on your project. The only restriction is about serial: if you don't have any serial module, you'll clearly have to use PDFUSB...

The following matrix sums up main features for both bootloaders, this may help you make your choice.

Table 1. Comparing Tinybld and PDFUSB bootloaders
Features Tinybld PDFUSB
Size 100 words, or 200 bytes ~2000 bytes
Timeout 1 second ~10 seconds
Communication link Serial USB
Serial adapter needed Yes No
Can reset PIC Yes, via RTS No

Tinybld installation and configuration

In order to get a fully functional Tiny bootloader, you'll need to act on several parts of Jaluino environment.

First, you need to program the bootloader itself. Follow instruction in previous Blink a LED section, and upload Tinybootloader HEX file bootloaders/tinybl/18f4550/tinybld18f4550_20mhz_external_48mhz_pll_115k.hex available in downloaded archive, or from Tiny booloader files SVN repository.

If you want to use Reset via RTS feature, you also need to put a jumper on J7, on Jaluino mainboard. This jumper must be put on the two most left connectors. Please refer Jaluino User Guide, section Hardware Setup. If you don't use this (leave J7 without any jumper, or jumper on the right connectors to activate RTS line), you'll need to push Reset button each you upload a program.

Figure 1. Reset-via-RTS feature is enabled with a jumper on J7

Finally, Jaluino IDE needs to be configured. Because serial link will be used to upload program to the microcontroller, you need to specify serial port and baudrate. Please refer to Jaluino IDE configuration and serial setup. If you didn't change any parameter in bootloader, you'll use 115200 bauds as speed. Serial port should be setup accordingly to your system.

Compilation and Upload default commands should also be set. You'll avoid common pitfalls, like compiling with wrong parameters. Open Jaluino IDE settings, and click on "General" tab. This is where you associate commands with file types. Select "Jalv2" file type, and choose "Jaluino with Tiny/18F" command as default. Just close the window in order your new settings to be saved.

Figure 2. Select "Jaluino with Tiny/18F" as default compilation command

Proceed the same about produced HEX files, uploaded to Jaluino. Select "Hex" file type, and choose "Tiny bootloader"

Figure 3. Select "Tiny bootloader" as default upload command

Except if you forced and specified other options in IDE, this setup will be used by default.

Let's try this by uploading our "Blink a LED" sample with Tinybld. Select appropriate sample following guidelines detailed in previous section. Make sure "Jaluino with Tiny/18F" is your compilation command, and click on "Compile". Jaluino IDE has generated appropriate command line, generated HEX file is ready to be uploaded.

Figure 4. Sample was compiled with appropriate parameters, compatible with Tinybld

Sample is ready to be uploaded, make sure "Tiny Bootloader" is selected in upload commands, and press "Upload" button. If Reset-via-RTS feature has been enabled, Jaluino will automatically reset and Tinybld2 will send program. If not, just press and release Reset button.

Figure 5. Tinybld has uploaded program.

Once uploaded, your program is immediatly executed, you should see your LED blinking.

PDFUSB installation and configuration

Closed to what done with Tiny bootloader, using PDFUSB requires you to act both on hardware and software sides.

First program the bootloader itself. HEX file can be found in archive, as bootloaders/pdfusb/18f4550_usb_bootloader_autostart.hex. You can also retrieve it from Jaluino SVN repository. Follow instructions detailed in Blink a LED section, in order to upload this file using a programmer.

Once done, you should configure default commands in Jaluino IDE, both for compilation and upload steps. Open Jaluino settings window, and click on "General" tab. Select "Jalv2" file type, and choose "Jaluino with PDFUSB" as default command.

Figure 6. Select "Jaluino with PDFUSB" as default compilation command

Proceed the same with default upload command. Select "Hex" file type, and choose "PDFUSB bootloader" as default command. Close window to save new settings.

Figure 7. Select "PDFUSB bootloader" as default upload command

PDFUSB is now configured. As it doesn't use a serial link, there's no for serial configuration. Remember PDFUSB can't reset a PIC running user's program: in order to upload a HEX file, you'll need to push Reset button.

Now, let's blink again our LED, this time using PDFUSB bootloader. Refer to Blink a LED section and open sample. Ensure "Jaluino with PDFUSB" is selected as compilation command, and click on "Compile" button. Notice the generated command line has changed and includes appropriate parameters.

Figure 8. Command line is automatically generated to support PDFUSB bootloader.

"PDFUSB Bootloader" should be selected in upload commands. Click on "Upload" button. Jaluino needs to reset to activate bootloader, so press Reset push button on board. Wait for a while, you should get PDFUSB output, claiming it has flashed your program. If you get an error, try again by pushing and maintaining Reset button, then click on "Upload", then release Reset2.

Figure 9. Program has been flashed

Using -x option, PDFUSB automatically resets and run user's program. You should see your LED blinking as soon as program was flashed. Note the next time Jaluino is turned on, you'll need to wait PDFUSB timeout (approx. 10 seconds) before your program is executed.

Common pitfalls...

Using bootloaders can sometime be surprising, if not frustrating. Keep the following in mind while using them.
  • Registers and fuses with Tinybld: when writing a program, you usually specify clock speed and type (internal, crystal, resonator...) and other parameters like selecting which pin carry PWM signals, watchdog, etc3.... These should have impacts on PIC registers, but when using a bootloader, these registers won't get programmed as you may think, as bootloader is the one which first has defined these. What you specified in your code isn't actually what was programmed ! For instance, Tinybld by default has been configure to run @48MHz. If you use another speed within your code, it won't be considered4.
  • Registers and fuses with PDFUSB: programs aimed to be used with this bootloader must be compiled with no-fuse option. Should you miss this option, registers will get overwritten and will break bootloader... You'll need to program it again.
  • Compilation options: beside -no-fuse for PDFUSB, you also need to specify how "far" it should jump. -loader18 4 with Tinybld, -loader18 2048 with PDFUSB. Don't forget it ! Because if you do, bootloader will never get executed first anymore. You'll have to program it again.
  • Serial baudrate: when using Tinybld coming with Jaluino, bootloader expects to communicate through a serial link @115200 bds. This is bootloader's speed, not user program's speed. Bootloader's and user program's speeds are independent, you can choose the one you need on your own program5.

This sounds scary, isn't ? Luckily, using Jaluino IDE default compilation commands, "Jaluino with Tiny/18F" and "Jaluino with PDFUSB", will ensure you're using correct options.

And, at the end, breaking a bootloader isn't that bad, you'll have a good reason to visit your friends !

1 Since it's part of user's program, this jump instruction will be written by the bootloader. Pitfall ahead !
2 USB timeline can sometime be tricky (observed under Linux), This sequence has been proved to work better.
3 When using jaluino_medium.jal library, as in all Jaluino samples, some registers are already set and hidden to users for simplicity, like clock speed and type
4 18F4550 is able to self-write its registers. Using PC host program Tinybld2, you can specify whether you want to write registers with your own defined. This option is not active by default: if incorrect registers are specificed (wrong clock, wrong baudrate), it'll just break the bootloader: it just won't work anymore....
5 PC host program Tinybld2 is smart enough to detect code which was compiled without -loader18 4 option. Clever.

Epilogue

Are you there ? Then... Congratulations !

Your Jaluino board and environment are now ready for further experiments. I hope you have enjoyed this first step, as much as I had writing and illustrating it...

See you soon and, in the mean time, have fun !



File attachments: 

Links

Following are hopefully useful links to several important websites and documentation related to Jaluino.

Jaluino licensing

Jaluino boards and shields

Following Arduino's original licensing, Jaluino reference designs for boards and shields, including schematics and PCBs, are released under Creative Common Attribution-Share Alike 3.0 license.



Basically (and repeating what's on Creative Common website), you are free:
  • to Share - to copy, distribute, and transmit the work
  • to Remix - to adapt the work
Under the following conditions:
  • Attribution - You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).
  • Share Alike - If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.

Full license lecal code can be read at: http://creativecommons.org/licenses/by-sa/3.0/legalcode

Just like Arduino, you can build your own version of Jaluino derived from original reference designs. But we'd like to keep the name "Jaluino" strictly related to original designs, those coming from Jaluino Team/Group, in order to maintain our own official standards.

Jaluino books and documentation

Jaluino user guide, tutorials and documentation in general is released under a more restrictive license related to commercial usage, the Creative Common Attribution-Noncommercial-Share Alike 3.0 license.



Basically (and repeating what's on Creative Common website), you are free:
  • to Share - to copy, distribute, and transmit the work
  • to Remix - to adapt the work
Under the following conditions:
  • Attribution - You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).
  • Noncommercial - You may not use this work for commercial purposes.
  • Share Alike - If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.

If any questions, suggestions or doubts, please reach Jaluino Group at http://groups.google.com/group/jaluino.

File attachments: