Project Lobster

From The Neuros Technology Wiki

Jump to: navigation, search

Neuros Technology | Products: LINK, OSD, Tablet | Developers


Project Lobster : OSD hacking for the masses

This document represents the manifesto and plan of action for Project Lobster.

This is an organized effort aimed at subverting the dominance of hardcore hackers on the OSD and bringing back to the masses the power to customize, enhance and generally screw up in unthinkable ways their Neuros devices.

Project lobster is a library written in lua to make it possible to use the neuros API (both widgets and media) from lua scripts. It needs the lua interpreter to work, of course. This is a work in progress (check frequently for updates). Generally this work is separated from the neuros code. This is not yet ready to enter neuros official SVN (almost there, though).

Project lobster uses the lua interpreter, which has been included in the official releases of the OSD firmware.

Also related to project lobster is the lua web stuff (for lack of a better name). This is made of two pieces: a web server that can run on the osd (xavante). and cgilua, which is a system for generating dynamic web pages (it does basically the same thing as PHP but it is based on lua instead). This seems to work from Nerochiaro's tests and Daurnimator is using it for his project. From Nerochiaro "I deem it completed and i'm not dedicating any time on it, although it might still need some testing and attention if bugs surface. I would say it's ready for entering neuros SVN. However it might not be wise to have it start automatically togheter with the OSD at the moment. Maybe we can have a menu option in the osdmain's Application menu to let people start/stop/restart it."

Current Status (updated 23 Jan 2008)

from Matthew Wild:

"I have working Lua modules for cooler core and media functions here:

They are fairly up to date, I rebuild them as necessary.

The only thing lacking is documentation - for that see the Neuros-Cooler source code, IRC, and this list."

from the mailing list thread

Previous Update: 4 Dec 2006

If you want to just lay your hands on some code, here's what we have so far:

  • UPK package with all lobster + unionfs for easier updates, [download here]. (WARNING: lobster in the upk is not up to date, use new version via unionfs).
  • Unionfs will soon enter official distribution, so lobster updates will become a snap.

Current work in progress (04 December 2006) that [you can find in SVN]:

  • API coverage: widgets.h: complete, needs some examples and tests. application.h : almost complete. media API: yet to be started.
  • Examples: rewritten to be a bit more organized, shows much more stuff. Still needs to be expanded.
  • Documentation: sorely lacking, only present in source comments. Need to build doxy-like quick extractor.

Previous Update: 22 November 2006

  • Cooler have been patched, finishing writing some construction callbacks (Listbox so far, others coming fast)
  • Keep up to speed with API changes
  • Updated example apps

Previous Update: 21 October

  • Autogeneration scripts (helps keeping stuff up to date with less effort and speeds up coverage)
  • Almost full widgets coverage (missing some problematic constructors that need callbacks)
  • Input events working (both from remote and keyboard via serial)
  • Some callbacks are still problematic, [investigating solutions] or [will patch cooler] itself.

Keep on reading the other sections to find out what we have in store.


  • We believe that every amateur programmer and skript kiddie has the right to try and have fun developing for these amazing devices without leaving their cozy scripting environment.
  • We concede that setting up a proper build environment is a scary scary task and cross compiling even more so. Such tasks are not for everyone and represent a serious barrier to entry for the casual hacker.
  • We also concede that even for terminal C geeks who sleep with their K&R book, scripting often is a quicker and more convenient way to prototype ideas and automate simple tasks.

In light of the above, we will proceed with the following:

Plan of action

The project will proceed according to the following plan of action, divided in milestones. This plan is flexible and can be amended in response to the suggestions and criticism that hopefully will start to pour in. Or if we simply realize that we had some very bad ideas.

Milestone 1 (bindings and stand alone scripts)

  • At the end of this step people will be be able create decently featured stand-alone applications that

can do most of what main app does.

  • To develop these they have to just to copy some pre-built binaries + their Lua scripts on a CF card.
  • To start the app they still have to telnet into the box, kill main app and run their script manually, but

no complex build environment is required.


  • Have a solid Lua bindings library available. It should cover:
    • Full Neuros-Cooler widgetry
    • Media stuff (Nms* functions)
    • Input handling
    • Lua libraries for file-system manipulation (lua-posix will probably do)
    • Bonus points for XML and HTTP lua libraries (shouldn't be hard)
  • Have binaries for all of this so people don't have to go through hell to setup build env.
    • Initially we will focus on a single stable Neuros release (3.18 at present).
    • Bonus points for no-fuss install script.
  • Investigate with Gao for some way to allow the users to disable the damn watchdog via config option.
  • Decide on a predefined directory tree for binary + scripts that allows for zero root FS installation (run all from CF, interpreter included since it's small).


Under active developement

Milestone 2 (osdmain launchers)

At the end of this step users will be able to start their scripts from the main application (osdmain) in the following ways:

  • We have a menu like the "Applications" menu that lists all Lua scripts on CF and allows to run them.
  • The file browser recognizes Lua scripts everywhere and allows the user to run them.

These scripts will run contained inside some kind of osdmain "sandbox". In other words they won't be able to interact with osdmain and at script exit osdmain will take back control. This can be enough for something like the flickr or youtube browser apps.


  • Patch osdmain Application menu & filebrowser to list scripts. Shouldn't be hard.
  • Define a protocol for scripts to get the initial resources they need (parent widget handle, bindings environment) from osdmain.
  • User input to script: find out if it's enough to just give focus to the script-created widgets to route all input to them, or if some other trickery is needed. Implement said trickery if that's the case.
  • Obviously have Gao accept patches to osdmain for all of this.

Status: Planned

Milestone 3 (osdmain event hooks)

At the end of this step osdmain will expose some system that allows interaction between user scripts and certain osdmain "events". Examples of this include:

  • "end of recording" event --> lua script sends an email message to the user, or plays a loud "FINISHED" mp3 file.
  • "end of track" event --> lua script sets up the next track based on some user-defined shuffle criteria.
  • "timer" events --> to trigger the execution of user scripts at predefined times (many possibilities here).


  • Clearly find out what "events" we want to make scriptable. For each of them:
    • Evaluate possible performance issues
    • Evaluate possible clashes with osdmain functionality
    • If event still makes sense, create patch to implement it in the most efficient way.
  • Define a dir structure/protocol to find the user scripts for events. Some preloading during startup might be more efficient.
  • If no script is defined for an event, either don't fire the event at all, or fire it with an efficient no-op function.
  • User scripts should have some API to register/remove events at any time.
  • Again, have Gao agree to all this.

Status: Planned

Why Lobster ?

Well, the lobster is a recurring in-joke in the neuros community ever since Joe's "mostly dead" lobster post. Plus, crustaceans are generally cool.

Also worth of note is that the original names for this all sucked big time: "the lua stuff" or lua-ncooler. If you can get people interested with names like these, either they're geeks, or you should work as a telemarketer.

But you want an acronym, right ? There: Lua Osd Bindings Simplify Tinkering, Enhancement and Reinventing. Happy ?

Personal tools