From 4ae719d05743f8ae1b8496a3d7806f324bdf568e Mon Sep 17 00:00:00 2001
From: sbosse <sbosse@uni-bremen.de>
Date: Mon, 16 Mar 2026 11:39:58 +0100
Subject: [PATCH] Mon 16 Mar 11:39:34 CET 2026

---
 doc/events.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 doc/events.md

diff --git a/doc/events.md b/doc/events.md
new file mode 100644
index 0000000..63e94a0
--- /dev/null
+++ b/doc/events.md
@@ -0,0 +1,100 @@
+## Events
+
+There are mainly three event classes:
+
+1. System events
+   + Device Events
+   + Timer Events
+   + Message Events
+2. Signal events
+   + Hardware
+   + Software
+3. User events
+
+Note: Event names are restricted to four unique characters. Longer names are allowed, shorter than 4 characters are not allowed. All system events must be registered by the hist application:
+
+```C
+AddEvent("class",index);
+```
+
+### Device Events
+
+Device events are registered by the host application. Each device event is characterized by a device class (e.g., ADC), and a device index (e.g., ADC 1). A device event handler is registered for a device class and a device index by using the `on event(<class>,<devindex> call` statement. Multiple handler procedures can be registered for one device class. The `event` variable can be used to identifythe specific device.
+
+
+```
+proc foo {
+  if event=0: ... // ADC 1
+  if event=1: ... // ADC 2
+}
+on event("adc",1) call foo 
+on event("adc",2) call foo 
+```
+
+### Message Events
+
+Message events are registered by the host application, but raised by the network  module.
+
+
+### Signal Events
+
+Signals are commonly implemented by digital logic and used for inter-node communciation. Evens are sent by using the `!>` operator. There are commonly request broadcast and consent (barrier) signal protocols, assigned to signal 0 and 1, respectively. The signal logic must be provided by the host application. 
+
+
+```
+event sig1=("signal",1)
+sig1 !> 
+sig1 ?   -- await event ("signal",1)
+```
+
+### Timer Events
+
+Commonly at least one timer (hardware or software) is registered.  In contrast to other peripherial devices, a timer must be started by using the `timer(<timerindex>,<millis>)` statement. A timer is stopped by using the `timer(<timerindex>,0)` statement.
+
+```
+proc foo {
+
+}
+on event("timer",0) call foo 
+```
+
+### User Events
+
+User events are created by using the `event` definition statement. An event handler (a procedure) is registered for a user event by using the `on call` statement. Inisde an event handler the event number can be accessed by the `event` variable. Multiple events can be bound to one handler procedure. A user evenr is raised by the `!` send operator without any argument and the event as the channel. User events can be used within a task or across tasks. 
+
+```
+event <uevA>[,<uevB>,..]
+proc foo {
+  if event=<usev> then ...
+}
+on <uevA> call <foo>
+on <uevAB> call <foo>
+<uevA> !
+```
+
+### Event alias
+
+```
+event <sysevA>=("class",index)
+proc foo {
+  ...
+}
+on <sysevA> call <foo>
+await <sysevA> delay <timeout>
+<sysevA> ? 
+```
+
+### In-line Event Handling
+
+In addition to event handler routines in-line event handling is supported using the `await event` statement. An await statement can be extended by a delay statement binding a timeout to the event awaiting.
+
+```
+await event(<evname>,<devindex>)
+await event(<evname>,<devindex>) delay <millis>
+-- Wait for timer event
+timer(0,2000) -- start interval timer 0 with 1000 ms period 
+await event("timer",0) .. wair for timer event
+```
+
+The *event* variable holds the event device index after an await statement or -1 if timeout or interuuption occured.
+