OSD Virtual Machine Development

From The Neuros Technology Wiki

Jump to: navigation, search

Please note that the author of the virtual machine packages is no longer maintaining them, thus you won't be able to use this development method anymore, unless you can prepare your own VM packages.




Application development for the Neuros OSD should be easy and fun and the good news is that it can be using Scratchbox running on Ubuntu Linux inside a VMWare virtual machine! This guide explains how to get your own virtual machine development environment up and running.

This virtual machine environment is ideal for hackers that just want to do quick application development without all the hassles of setting up an embedded development environment. It's also ideal for hackers that are new to embedded Linux development. This guide assumes knowledge of PC Linux development, but doesn't not assume a background in embedded development.

NOTE: There are alternate paths to setting up a development environment. If you are interested in doing lower level work such as at the kernel level or any of the other libraries that are created outside the Scratchbox developer environment. That environment is not described here but please see Derobert's Guide to Hacking the OSD for more information. In addition, you can do much of what is explained here with a simple Scratchbox installation on your Linux machine, if you don't think it's worth messing with yet another virtual machine. In that case check this guide to setting up Scratchbox for OSD development.

ENOUGH TALK ! If this sounds good to you and you want to skip all the babble and start immediately, skip directly to the setup instructions



Neuros wanted to create an environment that would be inviting to Linux developers, or even admins without previous embedded device development experience. Because the OSD uses a standard Linux kernel the possibility of applications is virtually unlimited. However, the inherent nature of embedded devices makes developing for them different than doing application development on the PC:

  • Host/Target development: Because the OSD has very limited resources, it makes sense to do development on a host PC instead, which dictates a modified development process
    • Cross-Compiling (compiling from PC to ARM target)
    • Netbooting (during development the OSD boots over the network from an image on the host PC
    • Physical Serial and Ethernet connection from OSD to Host PC
  • Package Management: Unlike the PC, the OSD is currently considered a controlled environment (like other CE devices) where the manufacturer is responsible for the "overall functioning" of the device, not just the hardware.
    • Upgrade package management. A tool is needed to provide a complete image in a single file that can update the entire device system.

In the beginning... Neuros developers received the kernel, a compiler toolchain for the ARM, and codecs. To this they added Nano-X, Neuros-Cooler, and many structures and abstractions. Along the way, makefiles begat makefiles, scripts begat scripts... and it somehow worked. Sort of. But it was not clean, or easy, and some issues seem impossible to sort out.

The whole system was confusing to developers who just want to compile existing source code. Most developers should be able to work without fussing with the constant base system build. The primary problem was the tight coupling between the base system build and applications that should sit on top of the base system. It was also difficult to take existing software out-of-the-box and compile it for the OSD.

Then along came Crweb who said there is a better way...


The better way was to create a complete development environment ready to go, prepackaged in a ready-to-go virtual machine image:

  1. Start with just the pieces that are needed after the base system is compiled. This includes:
    1. the kernel (as a cramfs)
    2. the root filesystem (rootfs)
    3. header and library files to build and link against (including Nano-X, Neuros-Cooler (gui toolkit), and others)
  2. Use Scratchbox. Scratchbox is a cross-compilation toolkit designed to make embedded Linux application development easier. It also provides a full set of tools to integrate and cross-compile an entire Linux distribution
  3. Put it all inside a virtual machine (VM) -- VMware is being used here. The VM is not absolutely necessary, but there are a lot of good reasons to do use a VM including:
    1. all the tedious configuration has already been done by a trained professional.
    2. a stable and consistent environment
    3. isolation from your other OS installation(s)
    4. there are also many VM specific benefits such as: taking a snapshot of your system, backing it up or distributing copies of it or even migrating it to a new host

In the new way, the steps to build a binary release of your software are:

  1. Build your application(s) inside Scratchbox, but as you normally would (e.g. `make install`)
  2. Package application(s) as custom firmware (.upk) or binary package



  • offers developers a consistent base for development based on Neuros's latest officially released firmware
  • offers a clean base allowing an out-of-the-box building of existing software:
    1. fetch software, and untar
    2. `make install`
    3. create the custom firmware or binary package from result
    4. clean, and repeat!
  • Provides tftp uImage, nfs rootfs which can be used directly for network boot (usually for the development/test cycle)
  • either gcc 3.4 or gcc 4 for compilation of applications
  • qemu-arm emulation for compilation of applications that do self tests (samba, php, sql's, apache)
  • easy to stay up to date with apt sources allowing instant updates to latest libraries, headers, and firmware file systems
  • additional benefits
    • isolation in virtual machine means predictable environment which doesn't interfere with your existing host system or require giving up super user permissions to host system.
    • doesn't require subversion (svn) access. So, people can develop without having anything to do with svn.


  • uBoot/rootfs updater [update to use any release, should be able to go back and forth between Neuros uBoot/rootfs releases]
  • tool to generate custom firmware (.upk) [simple, just working out details to make it nice]
  • tool to generate binary packages [simple, just working out details to only package up what is needed and coordinate with package installer]
  • package installer [not part of development environment per se]



Terminal Setup


HyperTerminal Windows comes with HyperTerminal, which works fine for monitoring the OSD. There's no need to connect within the VM since it's often more trouble and doesn't have any real advantages, see Setting_Up_Hyperterminal for a simple guide.

Putty The latest version of Putty can reportedly do the job as well.


This varies from distribution to distribution, but a description of the setup in Debian based distributions (and good starting point anyway) can be found in the "Configuring Serial section" of Derobert's Guide

Install VMware Player

  1. Download and install the VMware virtual machine player
    • For Windows: go to VMware's Free Virtualization Products page and download the Player. Follow all instructions for installation.
    • For Linux: there are multiple ways to get it but one is to use apt-get.
sudo apt-get install vmware-player

Not all distros, however, have installation so easy. Some distros do not offer proprietary software like VMWare as part of its default repositories - case in point, "blag" the UK "free software" distro (www.blagblagblag.org) based on Fedora.

Plus, there's an issue with VMWare Player 2.0 and the latest 2.6.22 kernels. There is a manual patching process that involves copying files and recompiling the VMware kernel module... but the good news is that Fernando Cassia has created a simple shell script that automatically downloads VMWare Player 2.0, downloads the patches, applies them, compiles the module, and leaves a working VMWare player. This script also works for Fedora Core 6, the distro upon which Blag 60000 is based.

Find more info here.

Virtual Machine

  1. Fetch the VM archive, the newest versions can be found at http://www.limesg.com/osd/buildenv
  2. Unpack the archive (you will want to put this somewhere that you have about 1.5 GB of space).
    • For Windows: WinRAR or Stuffit or a similar tool can do this for you
    • For Linux: just use tar
tar -jxvf NeurosOSD-DevVM-<the version number>.tar.bz2



  1. Start the virtual machine.
    • In Windows you can just double click on the file Neuros Development.vmx
  2. IMPORTANT! You will be asked if you want to 'Create', 'Keep' (recommended) and two other options for the vmware configuration. If you 'Keep' the image will work straight way but you may experience collision problems on the open internet because MAC addresses are supposed to be unique. If you experience these problems then try the 'Create' method. See the note below.
  3. Wait for Ubuntu to boot. After it boots you will see
NeurosOSD DevVM 0.2a neuros-dev tty1
Login: neuros  Password: neuros2
neuros-dev login: _
  1. Log in as the user neuros. The password is neuros2
  2. once booted, check to see if you have a working internet connection. This can be done in a number of ways, the simplest is to ping the neuros webserver
ping www.neurostechnology.com
  1. Find out the IP address of the VMWare instance. You need this if you want to copy files to and from the VMware image from your local machine. It is also useful if you want to use a windows ssh client or ssh editing tool, such as (X)Emacs Tramp mode, to edit the files in your virtual machine. To find the IP address of the active VMWare eth0 connection, examine the output of the command:
ifconfig -a 
  • Don't forget you have multiple tty consoles which you can switch between by using Alt and a function key F1 through F6. This is very useful when you want to have one console inside and one outside the Scratchbox environment.
  • Note* If 'ifconfig -a' does not show eth0 in the list then it probably has not 'come up'. This is because the MAC address in /etc/iftab in the client does not match the value in 'Neuros Development.vmx' from the VMWare image. When you 'recreate' the VMware client image it autogenerates a MAC address. This can be found via the property vmxfile:ethernet0.generatedAddress in the vmx file. You need to change the value for eth0 in /etc/iftab with the one from ethernet0.generatedAddress. you need root permissions to edit /etc/ftab. To log in as root use 'sudo -i' with the 'neuros2' password.


  • if you use DHCP on your router you will need to use ifconfig to find your VMware players IP ip address. To have it displayed every time you log into your virtual machine you can add the following line to your .bashrc
ifconfig eth0 | grep inet
window's network connections box
NOTE: In windows, The VM creates a couple additional network connections (with their own IP addresses). However, the ip you see from within the VM is really the only ip address you'll have to worry about, since it's the one you'll use to connect the OSD to as well as to connect to from windows
  • if you want to copy files to and from your local windows machine you can use scp or sftp. for those not familiar with scp, then sftp is probably the easiest method. You can use Putty, WinSCP, cygwin or any other scp/sftp clients for this.

Maintenance and Updating

To update your virtual machine to the latest ubuntu and neuros tools versions use apt-get after logging in

sudo apt-get update
sudo apt-get dist-upgrade

Answer yes to proceed with upgrade.

NOTE: This is highly recommended to be up to date with bugfixes of know problems.

OSD Netboot

The whole reason you went to the trouble of setting up this dev environment was to develop for the OSD, for that you need the OSD to netboot from an image on the virtual machine. For netboot, you will also need to configure the OSD uBoot (See NetBooting the OSD).

Develop, Build, and Test

In the home directory of the neuros login see the file Usage.txt for details. The basic steps are:

  1. place files to build in ~/Scratchbox-Home
  2. enter the scratchbox environment
  1. untar, build, and install as you normally would
  2. test using the built in tftp server (for netboot) and nfs server for the rootfs

Example: Build wget

This simple example will enable wget on the OSD.


  1. Download source to vm (most folks use the host machine to manage downloads and then transfer files to the vm)
  2. untar downloaded file
  3. "./configure" from the directory that was created when you untarred the wget download
  4. "make" from the same directory
  5. Clear out the scratchbox target filesystem
    sb-make menu screenshot
    . This will delete all the files from the scratchbox target filesystem meaning that after installing wget to it, that will be the only thing there. Thus we won't overwrite anything when we copy those files to the working OSD system directory.
  6. Reset the scratchbox environment by following the steps outlined in this Scratchbox article.
  7. "make install" from the directory that was created when you untarred the wget download
  8. type "exit" to leave scratchbox
  9. cd to home/neuros directory and check "Target-Rootfs" (which is a sym-link to scratchbox/users/targets/OSD) most of the subdirectories should be pretty much empty if the reset worked right (~1.5MB) depending on your version of wget)
  10. tar up Target-Rootfs: "tar -jcvf wget-package.tar.bz2 Target-Rootfs/*" (this is the wget package that's ready for install, in our case on the host nfs directory that the OSD will boot from)
  11. "cd /srv/neuros-osd-rootfs" This is the boot directory for the OSD
  12. "tar -jxvf /home/neuros/wget-package.tar.bz2" untars the package to the boot directory


Currently, the primary mechanism for releasing custom device software is the system upgrade package (upk file). These upk files allow a 3rd party to control the whole device enviroment which is often desirable for customized distributions of the OSD device for OEM applications. Documentation on that process can be found in the notes below.

NOTE: In addition to the UPK solution, work is underway to implement features that make the OSD more accomodating to third party applications, including unionfs, a window manager, a package manager, etc. Details on that ongoing discussion can be found at Refactoring OSDMain]

  1. exit scratchbox environment (or use another console)
  1. cp files installed by build process from Target-Rootfs to /srv/neuros-osd-rootfs file structure
  2. sudo mkcramfs /srv/neuros-osd-rootfs /opt/neuros/upk/root.cramfs
  3. Then follow the guide in /opt/neuros/upk (provided by the neuros-osd-extras package)
[TODO: replace this with script that does this]

[TODO: still need to define how to package for use, should be contained in a script... (1) packaging custom rootfs and other base files into .upk, (2) packaging just the built application into a package format that can be distributed and installed with package installer]


  • Since you are using a virtual machine you really don't need to ever shutdown. Instead you can just pause the VM using VMware's pause button.

If you do want to shutdown though simply type

sudo shutdown -h now

Then you can safely power down the virtual machine

Additional Information

Extra Packages

The Virtual Machine now uses an apt repo for updating and installing packages. New packages, and tools are being constantly added. Please check http://www.limesg.com/osd/repo for package names and descriptions. When new packages are added you can install them by:

 sudo apt-get install <new package name>

Did you want X with that?

The default Virtual Machine does not come with X11 or any other graphical tools. Although typically this work is done on the host machine, some users prefer to use their VM as their workstation. GUI desktops can be easily obtained:

 sudo apt-get install kubuntu-desktop   ( KDE/qt based )


 sudo apt-get install ubuntu-desktop    ( for you gnomey's)


  1. Add samba to the image and have it hooked up (to veth8 which is the localhost adaptor or similar? so as not to export the share?) to allow easier copying between running image and a windows host.
  2. instructions on how to set up a local cygwin Xserver to run Xapps on the VMware instance over an ssh link. Putty can easily be used for this.
  3. make subversion, cvs and git part of the default image.
  4. add a simple script to fetch the base codebase untar it and run the svn switch on it.
  1. samba installs for people to try
sudo apt-get install smb cvs git subversion
sudo smbpasswd -e neuros

change smb conf where top line is to replace below

<    workgroup = WORKGROUP
>    workgroup = MSHOME
<    security = user
> ;   security = user
< [homes]
<    comment = Home Directories
<    browseable = no
> ;[homes]
> ;   comment = Home Directories
> ;   browseable = no
<    valid users = %S
> ;   valid users = %S
<     writable = yes
>  ;   writable = no
<    create mask = 0660
> ;   create mask = 0600
<    directory mask = 0770
> ;   directory mask = 0700

Sample Code

With latest code from trunk, you can run GUI application (built with Neuros toolkit) too, you can find demo applications from [neuros-svn]/linux-r3-extra-apps/demos


Network not reachable error

allegedly due to a bug in vmware, host networking is being put on eth0 and bridged on eth1. Solution: edit /etc/network/interfaces and change the primary network interface from eth0 to eth1: change lines

    #the primary network interface
    auto eth0
    iface eth0 inet dhcp


    #the primary network interface
    auto eth1
    iface eth1 inet dhcp

TFTP timesout

Symptom: As the OSD is netbooting, it first tries to fetch /srv/tftp/neuros-osd/uImage from the VMware machine using tftp, but continually times out.

Solution: I found that the TFTP daemon (atftpd) isn't being called when incoming tftp requests are recieved (inetd should look after this). I found it easiest simply to run atftpd as a standalone daemon, which you can do by running the command "sudo dpkg-reconfigure --plow atftpd", and when it asks you whether the server should be started by initd, say no. Accept the defaults (make sure /srv/tftp is shared) from there on. Now atftpd should be running. --Greyback 06:48, 19 July 2007 (CDT)

Networking dies during startup

See Derobert's Guide Known Errors

Personal tools