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:
Holger Hans Peter Freyther
Neels Hofmeyr
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