Prerequisites

Before sweetly diving into Jaluino, you first have to:

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.

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.

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.

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.

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 generator¹. I hope you'll find enough information to pass this exam without getting bald.

Hardware setup

Option 1 will require several parts:

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 schematic².

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

Compiling and uploading software

Select Jaluino without bootloader in compiling options, and compile sample. You should get the following output, notably "Exit Code: 0" which basically means "success" !

Figure 4. Compilation output from Jaluino IDE

Amongst several files produced by jalv2 compiler is a file having *.hex extension. This file has to be uploaded to Jaluino. You'll need to use a programmer for this step. As there are many PIC programmers out there, not all are described in this documentation. Because it's widely used in jalv2 community³, uploading with Wisp648 programmer is explained in the following content⁴.

This pin layout is rather common and is at least used by widely used PICKit2 and Wisp648. If your programmer shows the same pin layout, you can directly plug it. If not, you'll need to use wires in order to connect correct pins together.

Figure 5. Wisp648 programmer directly plugged to Jaluino

Use software which comes with your programmer and upload HEX file.

With Wisp648, we'll use xwisp⁵ (GUI graphical frontend). You can also use xwisp2 (command line tool), you'll have to bypass Jaluino IDE and type commands from within a terminal or console.

Using xwisp through Jaluino IDE, just select "XWisp programmer" and click on "Upload". XWisp interface will show up.

Figure 6. Selecting XWisp programmer

Figure 7. XWisp application opened, HEX file loaded

In the opened XWisp window, press "Go" button, your HEX file will get programmed.

Figure 8. HEX file has been uploaded to Jaluino

Select XWisp2 binary according to your platform, and type (eg. Linux):

$ ./xwisp2u PORT /dev/ttyS0 GO ../samples/jaluino_medium_blink.hex
 xwisp2 version 1.9.6 for Linux (Dec 11 2008, Open Watcom C/C++ 1.70)
File ../samples/jaluino_medium_blink.hex loaded and is Intel Hex format conforming
Detected programmer: Wisp648, firmware version 1.29
Target: 18F4550 revision 06 (ID=1206)
Target erased
Transferring program to 18F4550 via Wisp648
Transferring program memory...100%
Verifying program memory......100%
Transferring data memory......100%
Verifying data memory.........100%
Transferring ID memory........100%
Verifying ID memory...........100%
Transferring fuses memory.....100%
Verifying fuses memory........100%
Write-Verify operation terminated successfully in 1.63 seconds
Putting target in run mode
xwisp2 terminated successfully in 2.00 seconds

Replace /dev/ttyS0 with your serial device file path, like /dev/ttyUSB0 if using a USB-to-serial adapter undex Linux, or COM1 if under Windows. If XWisp2 complains about not being able to detect target, or ends with some timeouts, unplug Wisp648 power supply for ~10secs, plug it and try again.

So HEX file has been uploaded to Jaluino, now can you see the LED blinking ? Is it alive ? Congratulations, you've been able to correctly setup your Jaluino board !

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.

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 beginning¹. 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 ?

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.

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 Reset².

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...

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 !

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.

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.