Derobert's Guide to Hacking the On-Screen Display: Complete

From The Neuros Technology Wiki

Jump to: navigation, search

Please note that this page is built automatically from the individual chapter pages. You'll have to make any changes on the chapter pages.


Hardware Setup

Note that there is no need to have the OSD powered up for these steps. It's probably better for it to be off.

OSD Ser. Cable, Null Modem Adptr. & USB adapter

Connecting the Serial Cable

To connect the serial cable to your computer, you'll need the following:

  • the headphone-plug to DE-9 cable that comes with the OSD;
  • an available serial port on your computer (including USB serial adaptors); and
  • male vs. femaleA male connector has pins (little pieces of metal sticking out); a female connector has receptacles for those pins. The male connector's pins insert into the female connector's receptacles (surely you can come up with an easy way to remember this!)either a null-modem cable or a null-modem adaptor. Both ends should be DE-9 female. Don't worry if you've never heard of DE-9 before; you've surely seen one (and you may know of it by the incorrect name "DB-9"). The link provides a picture of a DE-9 male connector.
    • NOTE. The OSD beta units sold through come with a null modem adapter included in the box. The production (black units) do not include a null modem adapter. The thinkgeek units also do not come with the USB serial adaptor.
    • NOTE. You may also choose to use a null modem cable. If you do not already own a null modem cable you may choose to rewire a standard serial cable. All you need to do is cross the red and white wires, so that one side's white is soldered to the other's red, and vice versa. Use electrical tape to isolate both connections, then resolder the copper braiding (ground). More comprehensive information may be found Here
  1. Connect the headphone-plug end of the OSD cable to the serial port on the OSD. The serial port is to the immediate right of the power adaptor port.
  2. Connect the DE-9 end of the OSD cable to one end of the null-modem cable/adaptor.
  3. Connect the other end of the null-modem cable/adaptor to your serial port or USB serial adaptor.

That's it for the hardware side of the serial connection.

Connecting the Ethernet Cable

"non-preferred" connection between OSD/Laptop

Thankfully, the OSD has a auto-MDI/MDIX (auto-crossover) ethernet port, so you don't need to worry about which type of Ethernet cable to use. There are two potential configurations covered by this guide:

  • Preferred. Connect the OSD to an Ethernet switch (or hub) on your LAN. Please note that by default the OSD boots with the IP address; if you already have a host with this IP address, wait until later to connect the Ethernet (after we've configured it to use DHCP).
  • Connect the OSD to an ethernet port on your laptop or other computer. With a laptop, this method is great for giving demos.

Do not worry if the link light does not come on; it may not come on until the software enables the Ethernet port.

Connecting the TV

Finally, use the supplied headphone-plug to RCA plugs cable to connect your OSD to the TV. If you're looking at the back of the OSD (so that the power adaptor plug is on the left), the TV out port is the second from the right.

You can also have a very comfortable setup if you install a tv tuner card in your PC. This allows you to have everything on your monitor. Is saves space on your desk and doesn't force you to keep switching focus between two different screens.

Just connect the RCA to the tuner input and the audio output of the card to the audio in of your soundcard (or directly to speakers). tvtime or kdetv are good choices for viewing the video output of the card, but there are several other alternatives.

Developers Remote Setup

If your clear backing OSD Dev kit remote stops working try this!

1. press and hold 'set' button, then press 'ntsc/pal', release both of them when led turns on
2. click button 0 6 4 sequentially, led will turn off after button 4 is pressed

Workstation Setup

This chapter is fairly Debian-specific. I've provided generic ways to perform these steps where possible. Your help in adding details for your preferred distro is much appreciated.

This thread on addresses how to open the firewall for NFS on RedHat Linux.

System Dependencies for Compilation

(NOTE: you need to follow this step only if you are not using the Virtual Machine Development Environment)

The following is a list of system dependencies that are required for setting up the OSD environment on your PC. Make sure that these packages are installed prior to setting up your development environment. If you're using a Mac, you can find alternative instructions on the MacWorkstationSetup page.

  • dialog
  • ncurses (generally you want ncurses-dev too)
  • mkcramfs
  • lrelease (found in Qt developlment tools Debian/Ubuntu qt4-dev-tools )
  • lupdate (found in Qt development tools Debian/Ubuntu qt4-dev-tools )

Configuring serial communications with the OSD

(Only in rare cases you might want to skip this step. That is, if you don't care about changing uboot parameters and doing all you work from telnet is ok for you)

In order to see and interact with the OSD's debug console, you'll need a serial communications program. This guide covers one called Minicom. If you're running Debian (or most Debian-based distros), you can apt-get install minicom. If you're using a Mac, you can find alternative instructions on the MacWorkstationSetup page.

One alternative program you can use is kermit. Skip this section and see the kermit configuration page for more information on this other program if you are using it.

You'll need to be a member of the dialout group in order to use the serial ports. If you're not a member already (use id to check), add yourself.

Next, determine the name of the serial device you connected the OSD to. Standard PC serial ports are called ttyS0, ttyS1, etc. If you've connected the OSD to a port on the back of your machine, it's probably one of those. USB serial devices are called ttyUSB0, ttyUSB1, etc. You can check dmesg for help:

anthony@Feynman:~$ dmesg | grep tty
serial8250: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
00:07: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
usb 2-4: pl2303 converter now attached to ttyUSB0

My OSD is connected to the USB serial adaptor, which the kernel has kindly told us is ttyUSB0. In front of the device name, put /dev giving the full name of /dev/ttyUSB0.

With that settled, it's time to actually configure Minicom. Replace ttyUSB0 with whatever your serial port is called:

  1. Run minicom -s /dev/ttyUSB0
  2. Select "Serial port setup"
    1. If "Serial Device" does not show /dev/ttyUSB0, type A and then edit it. Press enter to finish editing.
    2. Type E for "Bps/Par/Bits"
      1. Type I for 115,200 bps
      2. Type Q for 8-N-1
      3. Press enter to go back to the previous dialog
    3. If hardware flow control is "Yes", press F to change it to "No". This is important!
    4. If software flow control is "Yes", press G to change it to "No".
    5. Press enter to go back to the menu
  3. Select "Modem and Dialing"
    1. Type A, control-W, enter. This will clear the "init string". Note that the clearing may not show on screen until after you hit enter.
    2. Type B, control-W, enter. This will clear the "reset string"
    3. Press enter to go back to the menu.
  4. Select "Save setup a _dev_ttyUSB0"
  5. Select "Exit from Minicom"

Next, test it out:

  1. Run minicom /dev/ttyUSB0
  2. Power up your OSD
  3. When you see uboot countdown message press a key to stop it. If it stops minicom is set correctly.
  4. Try also typing at uboot prompt for further confirmation.

Configuring the Ethernet Cross-connect

This section only applies to those in the Hardware Setup chapter who wish to connect the OSD's Ethernet port directly to an Ethernet port on your computer.

TODO: Write this section.

NOTE: The OSD has an uplink auto-sensing Ethernet port. It will detect if the Cat5 is wired straight-through or crossover and adapt accordingly. A crossover cable is good to have, but not necessary.

Configuring TFTP

((NOTE: If you don't intend to Netboot your OSD, but want to just produce software for it and run it off media cards, or if you want to produce and flash UPK packages, you don't need to follow this step. You also don't need it if you are using the Virtual Machine Development Environment method, since TFTP will be setup from inside the VM already))

What is /srv?/srv is the standard location for site-specific data served by your machine. For more information, look at the Filesystem Hierarchy Standard.Install the atftpd TFTP server. On Debian, apt-get install atftpd works. If you're using Debian, you'll be asked some configuration questions (you may not be asked all of these, depending on your Debconf priority level. You can see them all with dpkg-reconfigure -plow atftpd):

  • I suggest letting the server be started by inetd.
  • The 300 second default server timeout is fine.
  • Leave the port to listen on as 69.
  • Leave the retry timeout at 5.
  • Feel free to lower the maximum number of threads.
  • Enable timeout, tsize, block size, and multicast support.
  • Leave the multicast port range and address alone.
  • Leave the TTL as 1.
  • LOG_NOTICE is a good verbosity level.
  • Important. Set the base directory to /srv/tftp
  • Log to a file instead of syslog (makes it much easier to find the logs); accept the default name.

If you're not running Debian, the command line options corresponding to the above are:

 --daemon --port 69 --tftpd-timeout 300 --retry-timeout 5
 --mcast-port 1758 --mcast-addr --mcast-ttl 1
 --maxthread 20 --verbose=5 --logfile /var/log/atftpd.log /srv/tftp

Next, go ahead and create /srv/tftp. Also, confirm that any firewall on your machine is allowing UDP port 69. A quick-and-dirty way to do this is:

# iptables -I INPUT -p udp --dport 69 -j ACCEPT
# iptables -I OUTPUT -p udp --sport 69 -j ACCEPT

However, if you're running a firewall on your workstation, you should spend some time figuring out the correct way to open the port required for TFTP.


see solution here.

Configuring NFS

((NOTE: If you don't intend to Netboot your OSD, but want to just produce software for it and run it off media cards, or if you want to produce and flash UPK packages, you don't need to follow this step. You also don't need it if you are using the Virtual Machine Development Environment method, since NFS will be setup from inside the VM already))

NFS can be a tad bit tricky to configure right. The first thing to remember is that NFS uses several dynamically allocated port numbers; in general, NFS and firewalls do not play along.

Installing the NFS server is fairly simple on Debian (and, indeed on most Linux distros — if it isn't already installed, that is):

  1. The package you need is called nfs-kernel-server. Go ahead and install it.
  2. Make sure that Portmap is set to listen on all IP addresses:
    1. Run dpkg-reconfigure -plow portmap.
    2. When asked "Should portmap be bound to the loopback address?", answer "no".
    3. Restart nfs by running /etc/init.d/nfs-kernel-server restart

The next step is to export a directory to become the OSD's root filesystem. This part is standard on any distro. First, mkdir /srv/neuros-osd-rootfs. Now, there are several different ways to configure your NFS export. Starting with the most secure:

  • If you know your OSD's IP address, use your OSD's IP address below where it says network-acl. Additionally, you may use "rw" instead of "ro" to allow your OSD to write to the share. Beware that there are some security implications of this and that it also makes your NFS environment not at all match the normal flash environment (which is read-only).
  • Network AddressThe quick method I describe in this section of determining your network address is actually only partially correct. The netmask can have things besides "255" and "0" in it. However, if you've configured a netmask like that, you probably already know enough networking to figure the network address on your own. If not, ask Google or install the ipsc, whatmask, etc. program.If you do not know your OSD's IP address (because, for example, it'll be configured with DHCP), the easiest thing to use is your-network/your-netmask for network-acl. If you don't know what those two numbers are, here's how to find out:
  1. Run /sbin/ifconfig. Look for your ethernet interface. It'll probably be called "eth0". It's the one which is not "lo."
  2. The number after "mask" is your-netmask. It should look something like
  3. Look at the number after "inet addr". If your netmask is, change the last number to a 0. If your netmask is, change the last two numbers to 0, etc. This is your-network So, in my case, I have an inet addr of and a netmask of giving me a your-network of (and a network-acl of
  • If you completely don't want to deal with this access control stuff, and just want to make it wide open, leave the network-acl blank. I strongly recommend that you do not use a rw mount in this case.

Now, edit /etc/exports and add this line (replacing network-acl as specified above):

 /srv/neuros-osd-rootfs network-acl(ro,sync,no_root_squash,subtree_check)

Arizona requires an additional export mounted rw:

 /srv/neuros-osd-rootfs/nfs-debug-extended-area network-acl(rw,sync,no_root_squash,subtree_check)

Finally, run /etc/init.d/nfs-kernel-server reload

Optional DHCP Server Setup

This chapter assumes a fair bit more experience than others and is thus optional. It also is not appropriate for all networks. This chapter only applies to you if you are running your own DHCP server on a computer. It does not apply if your DHCP is served by a SoHo router. In addition, this chapter will be of most use if:

  • Your DHCP server is running on Linux, xBSD, or some other Unix varient
  • You are running ISC DHCPd 3.x (check that version is 3.x and not 2.x).

Here is an excerpt from a dhcpd.conf file showing exactly what to do. In the excerpt, ... indicates omitted lines:

subnet netmask {
    range dynamic-bootp;
    host osd {
        hardware ethernet 00:18:11:80:10:1b;
        filename "neuros-osd/uImage";
        option root-path "";

Now, that alone doesn't mean much. Let's add some meaning:

  • 00:18:11:80:10:1b is the MAC address of my OSD.
  • is the IP address I assigned to my OSD.
  • is my workstation with TFTP and NFS running on it.
  • neuros-osd/uImage is where file name (in TFTP) of the OSD's kernel.
  • is the NFS share for the OSD's root filesystem.

Note that the fixed-address my OSD is using is not in the rang statement. This is important.

The First Compile

Obtaining the Source Code

The source for everything running on the OSD is in the SVN repository in the Neuros SVN repository.

Occasional tarballs are available here which may download faster. 

Please note: the OSD source repository was previously hosted at instead of If you still have code that reference these repositories you will need to either download the new ones or relocate your old ones. You can check if you reference the old URL by using the "svn info" command on your current repositories. Please consult this mailing list post for instructions on how to migrate your repositories.

Below are the instructions if you want to start fresh.

  • You can checkout the repositories that you need by checking out only one of them, and then letting an helper script do the rest. Here's the procedure (you will need to have the SVN client installed):
  svn checkout neuros-bsp
  cd neuros-bsp
  ./ checkout

This will take quite some time as it need to fetch a lot of data. Be patient.

With the above, you have just downloaded "trunk", which is the part of the repository where we keep the cutting edge and unstable version of the code, the place where all new commits end up. Trunk is sometimes broken, and it won't build or won't work sometimes.

You can always switch all your code to any of the tags or branches (which may be more stable), whenever you want, with this command, issued from inside neuros-osd:

 for d in $(ls) ; do svn switch$d/NAME $d ; done

You should replace NAME with either "trunk" or "tags/TAGNAME" with TAGNAME being any of the tag names in the page linked above (e.g. "OSD_VER_3.18-0.13_060919"). You can move to any tag or to trunk or any other way around whenever you want.

Finally, only if you're on trunk and want to update to get new commits that happened since last time, you can issue this command, from inside neuros-osd:

 for d in $(ls) ; do svn up $d ; done

Note that this makes sense only for trunk, because tags are snapshots and thus are fixed in time and don't ever receive updates.

So, choose the set of sources that makes more sense to you, and go on with the rest of the guide, always keeping the neuros-osd directory as the root for everything, unless otherwise specified.

Building the Code

Make sure you have dialog, ncurses, and mkcramfs installed. Arizona also requires debian's zlib1g-dev package.

Also note that these scripts require /bin/sh to be bash or linked to bash (this is not the default in some distros, for example newer Ubuntu, so please check).

Now all you need do to to build everything from scratch is:

 cd neuros-bsp
 ./ all

You will be asked for your sudo password (if you have not already entered it recently), and then you will need to answer "Yes" when asked if you want to run configuration for the Linux kernel on a blue screen.

The then be prepared to watch a good time while the build rolls.

Link here to help when the build fails, forums/IRC channel

Installing the Kernel for NetBooting

This one is fairly easy.

cd /srv/tftp
mkdir -p images
ln -s /PATH/TO/neuros-osd/neuros-bsp/images/uImage images/uImage

That's it. Make sure that the uImage file is readable by your TFTP server.

Alternatively, you can also copy instead of just symlink the uImage. This is easier to bypass permissions and other issues, but on the other hand needs to be done again at each rebuild of the kernel. I suggest putting it in a script togheter with the step below.

cp /PATH/TO/neuros-osd/neuros-bsp/images/uImage /srv/tftp/images

Installing the Root Filesystem for NetBooting

Installing the rootfs for the first time involves some messing about since you need to copy the /dev nodes that require some special permissions or nothing will work and your OSD boot will fail. We use tar for that. We need to do this everytime we change our rootfs, that is everytime we rebuild anything.

 cd /PATH/TO/neuros-osd/neuros-bsp/rootfs/fs
 tar --exclude '*/.svn*' -czf ../rootfs.tgz .
 mv ../rootfs.tgz /srv/neuros-osd-rootfs
 cd /srv/neuros-osd-rootfs
 sudo tar xzf rootfs.tgz
 rm rootfs.tgz

Notice that you need to be root when you extract the rootfs archive, so that created permissions are correct. If you don't like sudo, become root there in your preferred way.

(Note: Optional step, you can skip this) You can do the thing above everytime (possibly in a script so you don't wear off your fingers). Or you can use a little trick with rsync if you want to update only the changed files, once the /dev nodes are in place the first time.

 rsync --verbose --archive --delete --exclude "/dev/" --exclude "/mnt/" --exclude ".svn/" /PATH/TO/neuros-osd/neuros-bsp/rootfs/fs /srv/neuros/fs

This works for me, but your experience may differ, but it's optional anyway.

NetBooting the OSD


You need to have followed the Serial, NFS and TFTP sections in the Workstation Setup page. Alternatively, if you're using the Virtual Machine Development Environment, you need to have followed the instructions in there for netbooting setup.

Entering in uboot console

The first step is to get into uBoot.

  1. Start up minicom
  2. Power up the OSD
  3. When it says "hit any key to stop autoboot", hit the spacebar before the countdown expires.

Now that you're in uBoot, proceed to the correct type of configuration

  • DHCP — IP address assigned by a DHCP server
    • DHCP Method 1 — TFTP server and path as well as NFS server and path assigned by DHCP server, too. Appropriate for full DHCP servers running on Linux, xBSD, etc. (See also the DHCP server setup instructions).
    • DHCP Method 2 — Only IP address, network, and gateway assigned by DHCP server. Appropriate for SoHo routers. NOTE: This is probably what most people using DHCP need
  • Static IP Addressing — IP address, network, gateway, TFTP & NFS servers and paths are all configured staticly and stored in the OSD's flash.


Method 1

You must perform the optional DHCP server setup in order to use this method. This is the preferred method, but is generally only available if you're using a full DHCP server, not a SoHo router. It's not the most common situation.

This method is very easy, as nearly all the configuration information is stored on the DHCP server. The alternative is to store it all on the OSD as in Method 2 below.

setenv bootargs $(console) root=/dev/nfs rw ip=dhcp $(mem_reserve)
setenv bootcmd dhcp\; bootm

Method 2

This method is for use with your average SoHo router which provides DHCP, but doesn't allow you to configure things like TFTP server, NFS root, etc. If you're using a Linux machine for DHCP, you probably want Method 1.

setenv nfs_serverip your-workstation's-ip  # step 1
setenv nfs_root /path/to/neuros-bsp/rootfs/fs     #      2 
setenv serverip your-workstations-ip       #      3
setenv tftp_root /images                          #      4
setenv bootcmd dhcp\; run devkernel               #      5
run update-locs                                   #      6
run update-ipdhcp                                 #      7

Static IP Addressing

This is nearly the same as DHCP Method 2. Use those steps, except replace step #5 with these two:

setenv ipaddr the-osd's-ip-address
setenv bootcmd run devkernel

Also, replace step #7 with:

run update-ipstatic

The Boot

Type boot to boot the OSD or reset and let the coundown expire. Hey, at least some things are simple, right?

Reverting to booting from flash

If you want to revert to booting from flash, you can just do

  setenv bootcmd run cramfs_boot

Or you can just boot from flash once by doing

  run cramfs_boot

Known Errors

During boot, networking dies

Symptom: "nfs: RPC call returned error 101"

Problem: After the Linux kernel autoconfigures itself with an IP address, osdmain starts udhcpc which removes the IP address from the interface just long enough to confuse the NFS mount.

Solution: A patch is available; see bug 1873.

Old way: Boot from the firmware inside your OSD flash (see section above), then from OSD GUI configure the network for static addressing. Next time you reboot with NetBoot, this will prevent udhcpc from starting and causing the problem above by trying to get an address dynamically.

Unable to open an initial console

Symptom: "warning unable to open an initial console."

Symptom: "Kernel panic - not syncing: No init found. Try passing init= option to kernel."

Problem: By default, Neuros' supplied vm image comes with wrong permisions on /srv/neuros-osd-rootfs/dev/. RC scripts cannot create an initial console if /dev/ttyS0 is not setup properly.

Solution: run "sudo apt-get update && sudo apt-get dist-upgrade" to fix /srv/neuros-osd-rootfs/dev/ permisions.

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/xinetd should look after this). I found it easiest simply to run atftpd as a standalone daemon, which you can do by re-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:52, 19 July 2007 (CDT)--

I want to recover my flash (cramfs) with TFTP and netbooting without CF-card reader on computer

Symptom: As the OSD is netbooting, you can ask it to write the r3.upk package on the card, at the next reboot it will automatically recover from there (don't forget to run cramfs_boot after updating).

Solution: Put a CF-card in the OSD. Save the .upk you want to use as /srv/neuros-osd-rootfs/root/r3.upk. In /srv/neuros-osd-rootfs/etc/rc5.d/S99_osdmain add under "#!/bin/sh" the following line: " mkdir /media/CF-card1/newpackage ; cd /media/CF-card1/newpackage ; echo 1 > disable_upk_version_check ; rm r3.upk ; cp /root/r3.upk . ; rm /root/r3.upk ; reboot " . After the unit reboots, just unplug the ethernet to ensure you are no netbooting anymore. Wait while flashing.

Developing for the OSD

Code Examples

In the following linked pages are some examples of code to give you an idea of things you can do with the Neuros API.

Setting up remote debugging with the GNU debugger (gdb)

Sometimes you want to set a breakpoint into the guts of your program to see what's going on or you want to keep it in check so you can be there when it segfaults. The GNU debugger (gdb) can be setup to debug from the comfort of your PC (possibly with graphical frontends like ddd) while the actual program runs on the OSD: remote debugging.

  • Ensure you're inside a neuros build environment with source OSD/neuros-bsp/neuros-env (where OSD is the place where all your neuros sources are).
  • First you need to install on the OSD a lightweight version of gdb called gdbserver that will act as a brige between the debugged program and the actual gdb on your machine. This is already built and ready in the toolchain, you just have to copy it from $TOOLCHAIN/target/gdbserver to any place you want on your osd (let's say /bin).
  • Now let's suppose you need to debug a program called "foo".
  • On the OSD issue gdbserver x:5551 foo (5551 is the port, it can be changed to whatever you like, x is a random string, gdbserver doesn't care about it anyway). gdbserver starts the program and stops it immediately, then waits for a remote gdb to tell it what to do.
  • On the PC start gdb or any other frontend you like. Be sure to start it as arm-linux-gdb and not regular gdb.
  • From the gdb console open a copy of the program you want to debug (it can simply be the actual program on a NFS-mounted OSD root) with file /path/to/program/foo
  • Connect to the remote gdbserver with target remote (substitute the port with the one you used before to start gdbserver and the IP address with the actual one for your OSD).

That's it. You should see a message on the OSD console where you started gdbserver telling you it has received a remote connection. From now on you can normally use gdb as if the program was running on your machine.

Cross compiling with Scratchbox

((NOTE: It might be just easier, if you want to do any kind of work with scratchbox, to use the Virtual Machine Development Environment, which has an installation of scratchbox inside, and doesn't need much setup))

There's a whole page dedicated to setting up and using sbox to compile your 3rd party applications. Note that it's not for building stuff using the Neuros toolchain (although i think you can use pre-built neuros libraries with it if you want).

New: How to build the neuros code (Neuros-Cooler, Nano-X, etc) in SB. Still a work in progress, and it may change frequently until its stable.


Contributions to this Guide

This guide is an effort to consolidate the currently existing documentation on setting up a development environment for the OSD. The following documents were all used to form this new consolidated guide. These links are provided for reference reasons and may be used in case information is accidentally omitted.


Personal tools