Development‎ > ‎

Tier 3 Development - WristOS apps

WristOS operating system is the highest level API available for Dynawa TCH1 development. WristOS apps, written in Lua language and using WristOS API, are the quickest way to create real-world applications for TCH1.

Basic terminology:


is the system consisting of files in the "/_sys/" directory on TCH1's microSD card. You can analyze them but don't modify any of them.


are TCH1's applications. System apps, necessary for basic WristOS functionality, are located in the "/_sys/apps/" directory. Don't modify them! User apps (written by you and other Tier 3 developers) should be located in the "/apps/" directory and its subdirectories. Note that putting an app in "/apps/" directory doesn't mean it will automatically start when the watch reboots. You can have hundreds of apps present in the "/apps/" directory and only use a few of them.

An app is defined as "a directory that must contain a file named main.lua and may also contain other files (scripts and data)".

Each app consists of one or more tasks. Tasks are the actual Lua scripts. App is a collection of tasks. The first task corresponds to main.lua and other tasks of the same app usually correspond to other Lua scripts in the same directory (but don't always have to). Any task can access its app by evaluating the expression "".

Apps can (but dont't have to) produce a graphical output. At any given time, you can press the SWITCH button to switch between apps that currently produce graphical output.

Each app has its own unique id. This id is equal to the name of the directory where this app resides (including the trailing slash). Each task has also its unique id - the name of the script file which was used to start this task. This id is accessed by evaluating the expression "".


are primarily used for communication between tasks and thus between apps. A message is always a Lua table. The presence of various keys in this table defines various types of messages. Most of the messages have the "type" key which defines their type (a string).

Any task can send message by calling the function dynawa.message.send(message).

Any task can express its interest in receiving messages of type xy by calling dynawa.message.receive({message="xy", callback=callback_function}). Afterwards, any message of type "xy" generated anywhere in WristOS, is automatically delivere to this task's function "callback_function(msg)" as its argument.

Messages can also have the key named "receiver" which specifies their app. These messages are automatically delivered to all tasks of this app (if they want them).

Finally, a message can omit its "type" key. In that case, it must have keys "task" and "callback". The first one defines the receiving task and the second one defines the function in this task which will receive the message.

When the message is received, the receiver can check its key called "sender" which is automatically added by WristOS and specifies the task which generated this message.

Note that tasks cannot easily "respond" to a message. The return values generated by receiver functions are ignored by default. However, there is a special response mechanism available:  The message can contain a key named "reply_callback" which specifies a function in the sender task. In this case, the receiving task function must return a non-nil value (note that "false" is also a non-nil value) and this value is automatically sent to function specified by "reply_callback". Note that some messages can be received by more than one task and thus can (and must) return more than one value, in unpredictable sequence.