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.orgHolger Freyther has submitted this change and it was merged. Change subject: osmocomBB: Begin with a manual for the "mobile" application ...................................................................... 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, 200 insertions(+), 0 deletions(-) Approvals: Harald Welte: Looks good to me, approved Jenkins Builder: Verified 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..8828a72 --- /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..992a42e --- /dev/null +++ b/OsmocomBB/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 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> + <author> + <firstname>Holger</firstname> + <surname>Freyther</surname> + <email>hfreyther at 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/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: merged Gerrit-Change-Id: I736f2d61650feac70b6d960811b478639aa71737 Gerrit-PatchSet: 4 Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Owner: Holger Freyther <holger at freyther.de> Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org> Gerrit-Reviewer: Holger Freyther <holger at freyther.de> Gerrit-Reviewer: Jenkins Builder