Development‎ > ‎

Tier 2 Software Development (main.bin Lua interpreter)

You can begin your "Tier 2" development in two ways:
  1. Either: Analyze the default WristOS operating system (the Lua scripts"/_sys/" directory) and modify it to create your own operating system. Happy experimenting. Note that whatever you create, it will no longer be "WristOS", so please rename it.
  2. Or: Erase the microSD card (except the main.bin file), start (almost) from scratch and build your OS in Lua. This is described below:
The first prerequisite: You must have our original boot image (the file called "main.bin") present in the root directory of the microSD card.
The second prerequisite: You must have the directory called "_sys" present in your card's root and there must be a script named "boot.lua" in this directory.
The third prerequisite: Learn Lua.
When you switch the watch on, the following happens:
  1. The binary file "/main.bin" is loaded from the microSD card and executed. This file contains slightly modified Lua compiler and interpreter, as well as Dynawa Lua API functions which can be used by your scripts to control the hardware. Dynawa Lua API functions are documented here.
  2. The main.bin program attempts to load, compile and run the Lua script located in the file /_sys/boot.lua. This script (provided by you) must initialize whatever is necessary and then it must return from Lua back to main.bin. Before returning, it must also create a global Lua function called handle_event().
  3. Whenever any hardware event is generated (e.g. button is pressed, the timer expires, Bluetooth data is received), main.bin calls your handle_event() Lua function with a single argument: A Lua table containing the type of the event and optionally other data. These hardware events are explained here.
It's important to understand that although the main.bin is implemented using FreeRTOS, there is only one Lua environemnt and only one Lua thread at any given time. If there are several hardware events generated in rapid succession, your handle_event() function is called with the first event as its argument. Other events are held in main.bin's internal queue. Only after your handle_event() function does its job and returns to main.bin, only then is handle_event() called again, with second event as its argument.

Your handle_event() function must be able to handle the incoming events faster than they are coming. There may be occassional exceptions (that's why main.bin has its own event queue) but in the long run, the handle_event() function must be able to keep up with the incoming events. The trivial example: If you set repeated timer event to be generated each 10 milliseconds ad infinitum and handling each of these events in handle_event() function takes more than 10 millisecond, the main.bin queue will quickly overflow, taking the entire system down.

If you are proficient in Lua, you might create a system which provides a "fake multitasking" of sorts using Lua's "coroutine" library or using Lua events and messages but this is purely a Lua solution - our main.bin binary will not help you with multitasking in any way (although it uses "real" multitasking internally, you have no access to it from Lua}. If you want "real multitasking", you have to switch to (much more complex) Tier 1 or Tier 0 development.

The provided Lua interpreter is slightly modified so that its numeric operations are significantly faster when they only operate on integers and the results are also integers. Note that the Lua statement "local five = 10 / 2" is not an integer operation! See lnum patch documentation for details.

Next: See the documentation for Dynawa Lua API functions and hardware events.