summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/manuals/Makefile7
-rw-r--r--doc/manuals/chapters/scripting.adoc111
-rw-r--r--doc/manuals/osmocombb-usermanual-docinfo.xml57
-rw-r--r--doc/manuals/osmocombb-usermanual.adoc21
4 files changed, 196 insertions, 0 deletions
diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
new file mode 100644
index 00000000..9f861a56
--- /dev/null
+++ b/doc/manuals/Makefile
@@ -0,0 +1,7 @@
+TOPDIR = ..
+
+ASCIIDOC = osmocombb-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
+include $(TOPDIR)/build/Makefile.asciidoc.inc
+
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/doc/manuals/chapters/scripting.adoc b/doc/manuals/chapters/scripting.adoc
new file mode 100644
index 00000000..8828a72f
--- /dev/null
+++ b/doc/manuals/chapters/scripting.adoc
@@ -0,0 +1,111 @@
+[[scripting]]
+== Scripting using Lua
+
+The mobile application can be extended using the
+https://www.lua.org/manual/5.3/[lua5.3 language].
+To use the scripting facility a script needs to be
+configured through the VTY interface and will be
+associated to a Mobile Station (MS). The script will
+then be able to interact with the specific MS.
+
+An event based programming model is to be used. This
+means that once the script has been loaded it should
+register to the wanted events, configure timers and
+return. When an event occurs the registered event
+handler will be executed.
+
+The following describes the exported runtime services
+to be used in the script.
+
+=== Logging
+
+The logging functions allow to generate log messages
+for different levels. The log implementatiom is using
+the standard Osmocom logging framework which allows to
+have multiple log targets, e.g. syslog, file or through
+the VTY.
+
+|========
+|Code |Return | Explanation
+|print(...) |void | Print a message with log level 'debug'
+|log_debug(...) |void | Print a message with log level 'debug'
+|log_notice(...) |void | Print a message with log level 'notice'
+|log_error(...) |void | Print a message with log level 'error'
+|log_fatal(...) |void | Print a message with log level 'fatal'
+|========
+
+==== Examples
+
+----
+Code:
+print("Log level 'debug'")
+log_debug("Log level 'debug'")
+log_notice("Log level 'notice'")
+log_error("Log level 'error'")
+log_fatal("Log level 'fatal'")
+
+Output:
+\<0011> @script.lua:1 Log level 'debug'
+\<0011> @script.lua:2 Log level 'debug'
+\<0011> @script.lua:3 Log level 'notice'
+\<0011> @script.lua:4 Log level 'error'
+\<0011> @script.lua:5 Log level 'fatal'
+
+----
+
+=== Timer class
+
+The timer allows to invoke a function once after the requested
+timeout. The timer creation function will return immediately and
+the callback will be called after the timeout and when no other
+lua code is executing. The _osmo.timeout_ function should be used
+to create a new time, a running timer can be canneled using the _cancel_
+method.
+
+|========
+|Code |Return |Explanation
+|osmo.timeout(timeout, cb)|A new timer|Create a new non-recurring timer. Timeout should be in rounded seconds and cb should be a function.
+|timer.cancel() |Void |Cancel the timer, the callback will not be called.
+|========
+
+==== Examples
+
+----
+Code:
+local timer = osmo.timeout(timeout_in_seconds, call_back)
+timer:cancel()
+----
+
+----
+Code:
+local timer = osmo.timeout(3, function()
+ print("Timeout passed")
+end)
+print("Configured")
+
+Output:
+\<0011> @script.lua:4 Configured
+\<0011> @script.lua:2 Timeout passed
+----
+
+=== MS class
+
+The MS singletong provides access to the Mobile Station configuration
+the script is associated with. This includes runtime information like
+the IMSI, IMEI or functions like start/stop.
+
+|========
+|Code |Return |Explanation
+|osmo.ms().imsi() |string |The IMSI. It might be invalid in case it has not been read from SIM card yet
+|osmo.ms().imei() |string |The configured IMEI
+|========
+==== Examples
+
+-----
+Code:
+local ms = osmo.ms()
+print(ms.imei(), ms.imsi())
+
+Output:
+\<0011> @script.lua:2 126000000000000
+-----
diff --git a/doc/manuals/osmocombb-usermanual-docinfo.xml b/doc/manuals/osmocombb-usermanual-docinfo.xml
new file mode 100644
index 00000000..992a42e3
--- /dev/null
+++ b/doc/manuals/osmocombb-usermanual-docinfo.xml
@@ -0,0 +1,57 @@
+<revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>November 2017</date>
+ <authorinitials>HHPF</authorinitials>
+ <revremark>
+ Initial version.
+ </revremark>
+ </revision>
+ </revhistory>
+
+<authorgroup>
+ <author>
+ <firstname>Harald</firstname>
+ <surname>Welte</surname>
+ <email>hwelte@sysmocom.de</email>
+ <authorinitials>HW</authorinitials>
+ <affiliation>
+ <shortaffil>sysmocom</shortaffil>
+ <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+ <jobtitle>Managing Director</jobtitle>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Holger</firstname>
+ <surname>Freyther</surname>
+ <email>hfreyther@sysmocom.de</email>
+ <authorinitials>HHPF</authorinitials>
+ <affiliation>
+ <shortaffil>sysmocom</shortaffil>
+ <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+ <jobtitle>Co-Founder</jobtitle>
+ </affiliation>
+ </author>
+</authorgroup>
+
+<copyright>
+ <year>2013-2017</year>
+ <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, no Front-Cover Texts,
+ and no Back-Cover Texts. A copy of the license is included in
+ the section entitled "GNU Free Documentation License".
+ </para>
+ <para>
+ The Asciidoc source code of this manual can be found at
+ <ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+ http://git.osmocom.org/osmo-gsm-manuals/
+ </ulink>
+ </para>
+</legalnotice>
diff --git a/doc/manuals/osmocombb-usermanual.adoc b/doc/manuals/osmocombb-usermanual.adoc
new file mode 100644
index 00000000..b4059348
--- /dev/null
+++ b/doc/manuals/osmocombb-usermanual.adoc
@@ -0,0 +1,21 @@
+OsmocomBB User Manual
+=====================
+Holger Hans Peter Freyther <holger@moiji-mobile.com>
+
+
+include::../common/chapters/preface.adoc[]
+
+include::chapters/scripting.adoc[]
+
+include::../common/chapters/vty.adoc[]
+
+include::../common/chapters/logging.adoc[]
+
+
+include::../common/chapters/port_numbers.adoc[]
+
+include::../common/chapters/bibliography.adoc[]
+
+include::../common/chapters/glossary.adoc[]
+
+include::../common/chapters/gfdl.adoc[]