From ce39d03a668e7fa1c74eee589db6999cbd42edaf Mon Sep 17 00:00:00 2001 From: Holger Hans Peter Freyther Date: Wed, 15 Nov 2017 11:43:49 +0800 Subject: osmocomBB: Begin with a manual for the "mobile" application Begin with manual for the layer23 ("mobile") application but focus on the scripting code first. Change-Id: I736f2d61650feac70b6d960811b478639aa71737 --- doc/manuals/Makefile | 7 ++ doc/manuals/chapters/scripting.adoc | 111 +++++++++++++++++++++++++++ doc/manuals/osmocombb-usermanual-docinfo.xml | 57 ++++++++++++++ doc/manuals/osmocombb-usermanual.adoc | 21 +++++ 4 files changed, 196 insertions(+) create mode 100644 doc/manuals/Makefile create mode 100644 doc/manuals/chapters/scripting.adoc create mode 100644 doc/manuals/osmocombb-usermanual-docinfo.xml create mode 100644 doc/manuals/osmocombb-usermanual.adoc (limited to 'doc') 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 @@ + + + 1 + November 2017 + HHPF + + Initial version. + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + Holger + Freyther + hfreyther@sysmocom.de + HHPF + + sysmocom + sysmocom - s.f.m.c. GmbH + Co-Founder + + + + + + 2013-2017 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + 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 + + +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[] -- cgit v1.2.3