[PATCH] osmo-gsm-manuals[master]: osmocomBB: Begin with a manual for the "mobile" application

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Holger Freyther gerrit-no-reply at lists.osmocom.org
Wed Nov 15 03:49:40 UTC 2017


Review at  https://gerrit.osmocom.org/4838

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
---
M Makefile
A OsmocomBB/Makefile
A OsmocomBB/chapters/scripting.adoc
A OsmocomBB/osmocombb-usermanual-docinfo.xml
A OsmocomBB/osmocombb-usermanual.adoc
5 files changed, 189 insertions(+), 0 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/38/4838/1

diff --git a/Makefile b/Makefile
index cd1b10e..8261640 100644
--- a/Makefile
+++ b/Makefile
@@ -11,6 +11,7 @@
 	cd OsmoMSC; $(MAKE)
 	cd OsmoHLR; $(MAKE)
 	cd OsmoSTP; $(MAKE)
+	cd OsmocomBB; $(MAKE)
 
 clean:
 	cd OsmoBTS; $(MAKE) clean
@@ -25,6 +26,7 @@
 	cd OsmoMSC; $(MAKE) clean
 	cd OsmoHLR; $(MAKE) clean
 	cd OsmoSTP; $(MAKE) clean
+	cd OsmocomBB; $(MAKE) clean
 
 upload:
 	cd OsmoBTS; $(MAKE) upload
@@ -39,6 +41,7 @@
 	cd OsmoMSC; $(MAKE) upload
 	cd OsmoHLR; $(MAKE) upload
 	cd OsmoSTP; $(MAKE) upload
+	cd OsmocomBB; $(MAKE) upload
 
 check:
 	cd OsmoBTS; $(MAKE) check
@@ -55,6 +58,7 @@
 	cd OsmoMSC; $(MAKE) check
 	cd OsmoHLR; $(MAKE) check
 	cd OsmoSTP; $(MAKE) check
+	cd OsmocomBB; $(MAKE) check
 
 define check_dep_bin
     @type $(1) >/dev/null 2>&1 || { echo >&2 "Binary '$(1)' not found in path, please install $(2)."; exit 1; }
diff --git a/OsmocomBB/Makefile b/OsmocomBB/Makefile
new file mode 100644
index 0000000..9f861a5
--- /dev/null
+++ b/OsmocomBB/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/OsmocomBB/chapters/scripting.adoc b/OsmocomBB/chapters/scripting.adoc
new file mode 100644
index 0000000..e3cc951
--- /dev/null
+++ b/OsmocomBB/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/OsmocomBB/osmocombb-usermanual-docinfo.xml b/OsmocomBB/osmocombb-usermanual-docinfo.xml
new file mode 100644
index 0000000..c93d5e1
--- /dev/null
+++ b/OsmocomBB/osmocombb-usermanual-docinfo.xml
@@ -0,0 +1,46 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>August 2017</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial version.
+    </revremark>
+  </revision>
+ </revhistory>
+
+<authorgroup>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte at sysmocom.de</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</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/OsmocomBB/osmocombb-usermanual.adoc b/OsmocomBB/osmocombb-usermanual.adoc
new file mode 100644
index 0000000..b405934
--- /dev/null
+++ b/OsmocomBB/osmocombb-usermanual.adoc
@@ -0,0 +1,21 @@
+OsmocomBB User Manual
+=====================
+Holger Hans Peter Freyther <holger at 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[]

-- 
To view, visit https://gerrit.osmocom.org/4838
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I736f2d61650feac70b6d960811b478639aa71737
Gerrit-PatchSet: 1
Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Owner: Holger Freyther <holger at freyther.de>



More information about the gerrit-log mailing list