A VirtualBox Image for Compiling OpenSprinkler Source Code

I know, it has been a pain to compile OpenSprinkler 1.x source code, mainly because the firmware has grown to the point that you can only compile it successfully (i.e. within 32KB size) under a particular version of avr-gcc (4.5.3) in a particular version of Linux. This is very annoying for users who want to modify the source code and experiment with new features. That’s why I have decided to create a VirtualBox image with all the necessary software and settings that you need to easily compile it, without having to install a separate Linux system yourself.

Before you continue reading, please note that the VirtualBox Image is only useful if you are trying to modify the compile the source code yourself. To upload a pre-compiled firmware, you do not need any of these.

Wait, What?
VirtualBox is a free software that you can use to install and run a virtual operating system (OS) on your existing OS. Let’s say your computer runs Windows (i.e. the host OS). With VirtualBox, you can run a virtual OS (e.g. Linux) under the host OS, as if it is a Windows application but it’s a fully functional Linux system. This makes it easy to switch between different OS without having to restart your computer. VirtualBox is quite mature now. It makes use of hardware virtualization features available on most modern CPUs to provide fast speed. So even though you are running a virtual OS, it feels just as fast as a native OS.

One of the benefits of virtual OS is that the entire OS and all settings are stored in a single file — the VirtualBox Image — on your host system. So you can easily replicate the same virtual OS on different hosts by a simple copy-paste of the image file.

To make it easy to compile OpenSprinkler code, I created a VirtualBox Image for Linux Mint 13 with all the necessary software installed. You can download the virtual image file from here:

Warning: the file size is 2.1GB, so it will take some time to download. Meanwhile, you can read the instructions below.
User and Password: the virtual OS has a default sudo user opensprinkler and the password is the same as the user name.
VMWare Users: check this forum post for instructions of converting VirtualBox image to VMWare image.
Unzip in Windows: do not use the built-in zip/unzip tool of Windows because it seems unable to recognize the correct file size. Use a third-party software such as 7-Zip or WinRAR.

Step 1. Install VirtualBox

Download and install the latest version of VirtualBox from its official website. You should install the version corresponding to your host OS (Windows, Mac etc.). In the following I will use Windows as an example. After installing the software, you also need to install the VirtualBox Extension Pack. This is platform independent.

Step 2. Add a New Virtual OS
Unzip the file you downloaded to a local folder. I recommend creating a folder named VirtualBox VMs in your home directory, and unzip everything there. Next, run VirtualBox you just installed, and click on menu Machine -> Add. Navigate to the folder VirtualBox VMs \ LinuxMint13 and select the LinuxMint13.vbox file. Then click on Open to add the file. Now you should see an item named LinuxMint13 in the virtual OS list.

Click on Settings and make sure the default settings are compatible with your system. In particular, you should check if the Base Memory allocated to your virtual OS is not too large (it defaults to 2GB but depending on how much physical memory you have you may need to reduce it to 1GB).


Now you can click on Start to start the virtual OS. There will be a bunch of dialog boxes popping up with various information. If this is the first time you are using VirtualBox, you should read them thoroughly. Once the virtual OS boots up, you should see the desktop as shown in the following. If you want, you can press Ctrl-F to quit full screen mode, so the virtual OS will look like a normal Windows application running alongside with other applications.


Step 3. Compile OpenSprinkler Code
Arduino 0023 is pre-installed in the virtual OS. So you can just double click on the desktop icon to run it. Also, firmware 1.8.3 source code is pre-installed. So all you need to do to get started is to go to menu File -> Examples -> OpenSprinkler -> interval_program and then you can compile the code directly. If you need to change and file, or update to new firmware source code, everything is located in the arduino-0023/libraries/OpenSprinkler folder on the desktop.


Note: the following two steps are revelent:

  • Specify your hardware version by opening file arduino-0023/libraries/OpenSprinkler/defines.h, and uncomment one of the lines #define SVC_HW_VERSION that corresponds to your hardware version. To identify your hardware version, check the version number printed at the top of your OpenSprinkler circuit board. The current version is 1.4.
  • If you own OpenSprinkler v1.0 or 1.1, you can no longer upload a program through FTDI. Instead, you need an external ISP programmer. An inexpensive USBtiny programmer is available at Rayshobby Shop.

Step 4. Upload Compiled Code
To upload the compiled code to your OpenSprinkler controller, first connect OpenSprinkler to your computer through the USB port. Then go to the VirtualBox software, and click (in the menu) Devices -> USB Devices -> USBtinySPI. This will allow the OpenSprinkler’s built-in USBtiny programmer to pass through directly to the virtual Linux and appear as a native device. Finally, click on the Upload button in Arduino and you are all set.


That’s all. Hope my effort is helpful for those who want to compile OpenSprinkler source code. Feel free to leave comments, and enjoy playing with the virtual Linux!