OSD 2.0 Development

From The Neuros Technology Wiki

Jump to: navigation, search

This the place where you can find developer documentation and resources for the device code named the OSD 2.0 which is a part of the Neuros Open Internet Television Platform


OSD 2.0 Hardware

The OSD 2.0 is available on the Neuros Store for $249.99 complete in a housing, etc.

The OSD 2.0 is a platform from which numerous products will be built, both by Neuros and other third parties, the OSD 2.0 Page has information on this hardware.

Design documents are currently under development, in the meantime, here's a link to the ML intro:

OSD 2.0 Spec & Thread

The OSD 2.0 is based on TI's Davinci 6446 SoC. This SoC has publicly available documentation available on TI's site and TI's DaVinci/OMAP Wiki.

Here's also some information on the OSD2 in the context of previous OSD products: OSD Platform Information (pdf)

Developer Support and Contacts

Since the system is still in an early development stage, many things are subject to change, both in hardware and software. We make an effort to keep this documentation up to date, but it's easy to stuble into something that's not documented here or outdated. Subscribe to open.neurostechnology.com for the latest news.

Because of this, at the moment the best resource for last minute changes is the IRC channel #neuros on freenode.net. It's staffed more or less 24 hours on workdays with greatest activity during American and European daytime, but weekly meetings are held for more structured discussion.

VLC port meeting is every Thursday 10am CST (UTC 15:00)

Development Milestones


Developer Documentation

This documentation is aimed at developers that own an OSD2 bare boards. If you are looking for information on specific indepth Software Development please see Development Resource after following this guide. There are various revisions of current OSD2 hardware, with various degrees of completeness. If you are receiving a board that shipped prior to July 30th 2008, you should read the memo about known hardware issues and workarounds. There may be still other hardware issues on this board, so if you have one and suspect hardware fault, please notify us immediately (IRC, or bugzilla).

This documentation will be updated again as we ship the dev kits with the board in a mini-itx case (initially 300 pieces, available approximately August 8) which will have guaranteed final and complete hardware (we'll upgrade you at our expense if that's not the case). Bare boards are available without the case today.

Below is the build and setup instructions to create and boot a base Linux system. It does not currently have any real multimedia capabilities as it lacks codecs and a media server. They are under development and stuck by some licensing issues. See below for more.

One-time build environment setup

0. You will need your build station to have the following pre-requisite packages installed:

  • The usual essential build packages, such as `make`
  • The source control tool `git` (sometimes called also `git-core` depending on distribution) in version 1.5 or later (support for 'git config' and --rebase is needed)
  • `fakeroot` utility, to pretend you're root when building rootfs images

All you need to do is to make sure fakeroot is installed, for example, depending on your Linux distribution, either 'yum install fakeroot' or 'apt-get install fakeroot' will do the trick.

  • `mtd-utils`, needed for the `mkfs.jffs2` utility.

First make sure you have 'mtd-utils' or 'mtd-tools' package is installed.

  mkfs.jffs2 -V

If this returns the revision number, it is good to go. Otherwise try either 'yum install mtd-utils', 'apt-get install mtd-utils' (Debian Lenny/Sid), or 'apt-get install mtd-tools' (Debian Etch) depending on what Linux distribution you are using.

Please note that in many distribution this utility is only available in a path like /usr/sbin that is only in superuser's PATH. You will need to make sure it's available in the PATH of the user that's doing the build too.

1. Select a directory on your machine. We will call it ##WORKDIR from now on. Most of the work is to be performed from this directory, unless noted otherwise:

  cd ##WORKDIR

2. Bootstrap the initial git repository that will allow you to setup all the others.

  git clone git://github.com/neuros/build-tools.git

In Debian Etch, you may need to follow the instructions in the transition script that appear when you type the above command.

Please note: the URL above is new as of 24 Sep 2008. If you have the old repositories already, you need to switch to the new URL. If this your first time, you don't need to worry.

3. Fetch all the rest of the source code via helpful script (and get a cup of coffee as it can be quite slow in performing this operation):

  ./build-tools/scripts/git-helper.sh clone

5. Create some extra scripts and directories in the source tree, generates top Makefile customized to your environment etc. Please notice that if you move your tree into anoher dir, you will need to run this again


Build instructions

After you take care of the one-time setup of the build environment as above, to entirely rebuild your system you need to do the following steps.

1. Make sure your source tree is up to date

  ./build-tools/scripts/git-helper.sh clone

This will clone all newly created repositories for you since you last cloned. It is always safe to do this, all already cloned repo will automatically be skipped.

  ./build-tools/scripts/git-helper.sh pull

This will check to pull updates for each repo.

Step 1 is Optional but recommended for a complete system rebuild.

2. Set up environment variables used by the build scripts to find everything they need. You will need to run this everytime you log in again in a new shell before you can (re)build.

  source neuros-env

3. Simply run the top-level Makefile to build and install everything (run without options for some help):

  make all install

This will generate various images in the generated "images" subdirectory of your ##WORKDIR. Some useful files that get created there are:

  • u-boot.bin : u-boot bootloader image
  • default_env.img : u-boot environment variables image
  • uImage : Linux kernel image
  • rootfs.yaffs2 : Root file system image
  • osd20.pkg : package for emergency update, contain all the above. you can put on a card and re-flash the entire device with it (see below)

Example: Building on a fresh, clean install of Ubuntu 8.04.1.desktop.i386

(linux headers may not be required)

   apt-get install git-core
   apt-get install fakeroot
   apt-get install mtd-utils
   apt-get install mtd-tools
   apt-get install linux-headers
   apt-get install linux-headers-2.6.24-19-generic
   apt-get install build-essential
   apt-get install mono-gmcs
   apt-get install zlib1g-dev
   apt-get install libdbus-1-dev subversion gettext cvs
   git clone git://github.com/neuros/build-tools.git
   ./build-tools/scripts/git-helper.sh clone
   ./build-tools/scripts/git-helper.sh clone
   ./build-tools/scripts/git-helper.sh pull
   source neuros-env
   make all install
   # required for vlc
   apt-get install autoconf automake libtool libsdl1.2-dev

Installing on your device

You have two basic choices here: flashing the image on the device or net-boot.

Flashing the image

You can flash the package generated by the build in images/osd20.pkg

Place it on an MMC/SD card in newpackage/osd20.pkg and plug it into the reader, then reboot the device. The bootloader will automatically start to flash the image. Do not unplug the power while this happens as you can make your device un-recoverable if you interrupt the flashing before it's complete. It takes a very short time to update the entire device, one minute or two at most (if you were used to the long flashing times of OSD1, rejoice).

After the update is complete, the system will automatically boot. I suggest you to remove the file from the card, or remove the card from the slot before you reboot again, because right now the updater in the bootloader will keep installing it regardless of the version. This will change in the future when we will use versioned pgk for emergency update.

Another thing to notice when you do this, is that your u-boot environment will be reset to factory values. So if you modified some variables, they will be gone and you will need to reset them. (TODO add some notes here on how to save and restore uboot envs)

Net-booting your device

This is a more complex procedure that will allow you to run your device from your PC, allowing to edit in real time files in the device file system without need to reboot, or try new kernels without the need to flash them.

1. You first need to setup a TFTP server on your host machine. Instructions on how to do this are the same as for OSD1, so i'll just link you to the TFTP setup chapter. The only difference is that you want to point your TFTP root to ##BASEDIR

2. Then you need to setup NFS on your host machine. Again, the NFS setup chapter in there is what you need. The only difference for the NFS setup is that when you edit /etc/exports you should only add this line:

   ##BASEDIR/rootfs/nfs-rootfs network-acl(rw,sync,no_root_squash,subtree_check)

3. Then you need to install the rootfs in a way that can be booted. To do this, you need to be able to gain root privilege, since we will need to install some files as root (you may be asked for password when you run the command below):

   make -C rootfs install-nfs

4. The above command will create a directory named rootfs/nfs-rootfs which is the directory that the OSD2 kernel will try to mount with NFS. Each time you do a modification that affect the rootfs, you run again the above command to transfer it to the live rootfs (and of course you can also manually edit files in nfs-rootfs, but be aware that they may be over-written by further runs of the command).

5. Force NFS server to reload the configuration. In debian and ubuntu it's the following command. But may be different for your distribution:

   /etc/init.d/nfs-kernel-server reload

6. Now we need to configure OSD2 to pick kernel and rootfs and use them to boot. To do this you need to access uboot console via serial port. If you have a bare board, the connector is labeled J14 (left-most when facing the side, see also pictures on OSD2 HW page). It should be labeled on the outside of the case if you have the mini-ITX case version. Once it's connected, follow the Serial setup chapter on OSD1 setup guide to know about adapter cable and terminal parameters.

7. When serial setup is done, reboot the OSD2 and at the uboot timeout press any key in serial console to stop it and access uboot prompt. Then type the following commands:

   setenv bootcmd run devkernel
   setenv ipaddr ##YOUR_OSD2_IP
   setenv serverip ##YOUR_HOST_IP
   setenv tftp_root /images
   setenv nfs_root ##BASEDIR/rootfs/nfs-rootfs
   run update-locs
   run update-ipstatic

8. Finally reboot and see if it works. If it fails immediately after it start to boot, it's TFTP that didn't pick up the kernel image. Otherwise you will see "Uncompressing Linux...." followed by a lot of dots and the Kernel will boot. Then if NFS isn't setup correctly, you will get errors later about kernel not able to mount the root file system. Otherwise, enjoy your login prompt !

Building with Open Embedded

See OpenEmbedded_OSD2 for instructions. It's still a work in progress, both the guide and OE, and at best right now you will get a basic Linux system that boots if flashed (but not from NFS). It's also at the moment quite different than the one you build with the regular build instructions above.

We are looking however in making OpenEmbedded the main tool to build the OSD2 system.

VLC, Codecs and Multimedia

Currently we are still in negotiation with Texas Instruments to obtain a deal for releasing a few components as GPL. They are released as binary for now:

  • cmemk (out-of-kernel memory manager) and dsplink (DSP interface) kernel modules. We currently can redistribute this only as module
  • codec engine (CE). A library to allow applications, in this case VLC to interface with the DSP).

You find both in the binary-components repository.

In addition there are the DSP codecs themselves. These are binary only by design and they don't consitute a violation of GPL as they run on the DSP. These codecs live in the binary-components repo too, and are installed in /opt/ticel on the device.

Alongside with this, we porting of VLC is in progress as the main multimedia framework on the OSD2, in collaboration with M2X. VLC will run in server mode and applications will talk to it via a DBUS IPC interface.

Currently VLC is not built as part of the main build script explained above. It can be built separately with the following command, after you have built the rest of the system:

   make vlc

It will take a long time the first time you issue it since it have to download its own many dependencies (some pretty huge like ffmpeg) and build them all.

Once this finish, you will have it already installed in the rootfs, you should NOT run make install afterwards on toplevel or it will be removed (it's a limitation we're working on fixing). According to your preferred installation method you should either nfs-install the rootfs or run images/build_pkg again to regenerate the UPK.

At runtime, it's currently very limited, as the porting is still in progress, and you have to follow some pre-requisites.

One is to run vlc only after going into a specific directory, /opt/ticel, this is the only wav vlc can find codecs and thus play some video. (if you update binary-components after Sep 1st 2008, this restriction is removed, you can run vlc from anywhere.

Please check Development Resource page to find out how to run vlc with the correct options to be able to do playback, record, and pass-through.

Application Development and Command Line Reference

Now that your OSD2, build system, and rootfs are completely setup you can dive into application development. The Development Resource Wiki is a great place to see some of the indepth details of Neuros Platform development. Also, applications source code is a great place to start hacking and learning Qt4 and C++.

U-Boot Recovery & Upgrade

When things start to fail, we can start here.


UBL is the U-Boot Loader. NAND blocks can become bad through time and flashing. UBL is installed on the first block of NAND in order to load u-boot if the first block of u-boot had to be moved to a new location. UBL is upgraded 2 ways. First by OSD2 flash package file. Second way is by building TI's DVFlasher. DVFlasher.exe contains the UBL in the executable file. It is important to always use the most current DVFlasher version. See below "Flashing U-Boot via Serial port" for more information.

U-Boot Configuration

If it is reported that the env in u-boot is corrupt and default is being used you can upload the neuros osd2 env by copying images/default_env.img to the same location as your uImage.

This configuration can be reinstalled by the following command.

   setenv serverip <your servers IP>
   tftp 82000000 /images/default_env.img

Manually Upload uImage

To manually upload the kernel uImage use the following command.

   setenv serverip <your servers IP>
   tftp 82000000 /images/uImage

Flashing U-Boot via Serial port

The OSD2 uses 2 systems for booting from NAND memory. First system is UBL which is stored on the first block of memory and points to the first block of u-boot in case other blocks go bad. Neuros uses a tool called DVFlasher that is provided by TI in order to flash new UBL and U-Boot to the NAND memory. The DVFlasher executable file includes the UBL in the binary so the version of DVFlasher reflects the version of UBL that will be installed. This is an *important* note because flashing the wrong UBL could be a problem. Always make sure your DVFlasher is up to date.

*IMPORTANT NOTE* THE DVFlasher Utility has been retired and is no longer being supported. The replacement utility, Serial Flasher Host, is very similar but requires the user to provide a UBL binary as part of the command line. Interested users can find the new utility as part of a booting and flashing utility package on Sourceforge (select the DM644x version). This new utility has been released under the GPLv2 and includes source for a common UBL configuration. The build also now uses the CodeSourcery ARM cross-compiler tools. Further details can be found on the TI DaVinci Wiki.

First build the Development environment in linux then copy the images/u-boot.bin to a good location.
Please contact developers for instructions on how to build DVFlasher from sources.
   Grab newest DVFlasher from: DVFlasher.exe
   In Linux (Mono versions 1.6.1 and 1.9.2 confirmed to work):
   ./DVFlasher.exe -p /dev/ttyUSB0 -fnandbin u-boot.bin   (ttyUSB0, ttyS0, etc)
   In Windows:
   DVFlasher.exe -p com1 -fnandbin u-boot.bin    (com1, com2, etc)

Next, you must reinstall the OSD2 u-boot configuration. Please see above to restore Neuros OSD2 u-boot configuration.

Target Audience

Neuros' primary interest is in creating a target for 3rd party application developers to port to. Our feedback from the market tells us there's a great market for that. So, for example, there's more and more television content available on the internet now, and clearly there's a great desire to "get internet television on the television" but rather than forcing those studios to get in the hardware business we offer a target to port to. Not only does it avoid distraction for the content providers, but it's a vastly better user experience than five set top boxes with five remotes! Now most of those content providers, aggregators and applications writers are left them with the media center pc hooked to the TV, which is fine, but typically loud big and expensive. The OSD2 provides an open electronics option that allows them to bring their content and applications directly to the TV set, using an open. silent, inexpensive solution that leaves them with a direct relationship that they control with their viewer. Get the intermediary (operator or hardware manufacturer) out of the way, and give the viewer the experience they want. If this sounds like a compelling option, please contact Neuros at busdev (at) Neurostechnology.com

Beta Testers

Neuros is looking for beta testers! Please sign up for our OSD2.0 HD Platform newsletter today.


How to enable S-Video output and use it

Personal tools