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
This commit is contained in:
parent
bcd13f4d27
commit
ce39d03a66
|
@ -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
|
|
@ -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
|
||||||
|
-----
|
|
@ -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>
|
|
@ -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[]
|
Loading…
Reference in New Issue