HMS CANbridge NT User Manual
CAN@net NT/CANbridge NT
Lua ADK
USER MANUAL
4.02.0332.20002 1.2 en-US ENGLISH
Important User Information
Disclaimer
The information in this document is for informational purposes only. Please inform HMS Networks of any
inaccuracies or omissions found in this document. HMS Networks disclaims any responsibility or liability for any
errors that may appear in this document.
HMS Networks reserves the right to modify its products in line with its policy of continuous product development.
The information in this document shall therefore not be construed as a commitment on the part of HMS Networks
and is subject to change without notice. HMS Networks makes no commitment to update or keep current the
information in this document.
The data, examples and illustrations found in this document are included for illustrative purposes and are only
intended to help improve understanding of the functionality and handling of the product. In view of the wide range
of possible applications of the product, and because of the many variables and requirements associated with any
particular implementation, HMS Networks cannot assume responsibility or liability for actual use based on the data,
examples or illustrations included in this document nor for any damages incurred during installation of the product.
Those responsible for the use of the product must acquire sufficient knowledge in order to ensure that the product
is used correctly in their specific application and that the application meets all performance and safety requirements
including any applicable laws, regulations, codes and standards. Further, HMS Networks will under no circumstances
assume liability or responsibility for any problems that may arise as a result from the use of undocumented features
or functional side effects found outside the documented scope of the product. The effects caused by any direct or
indirect use of such aspects of the product are undefined and may include e.g. compatibility issues and stability
issues.
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
Table of Contents
Page
1 Purpose of this Document .................................................................................................. 3
2 Description of Ixxat Lua ADK .............................................................................................. 4
2.1 Difference between Standard Lua and Ixxat Lua ADK.............................................................. 4
2.2 Lua Library Functions Enabling the Registration of Lua Callbacks ........ ......................................4
2.3 Limitations of the Ixxat Lua ADK ............................... ............ ............................... ............ ... 5
2.4 Specifics in Coding for the Ixxat Lua ADK ....... ............................... ............ ............................5
2.4.1 Bit Model 32 Bit Version. . . . ...... . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ..... . . . ...... . . . . ..... . . . ...... . . . ...... 5
2.4.2 Errors and Debugging . . . ..... . . . . ...... . . . ..... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . . 5
2.4.3 Declaring Variables . . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ..... . . . . ..... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ... 6
2.4.4 Passing Context between Lua Event Tasks. . ...... . . . ..... . . . . ..... . . . . ..... . . . ...... . . . . ..... . . . ...... . . . ..... 6
3 Using Lua ADK with the CAN NT Devices........................................................................... 7
3.1 How to Enable the Use of the Lua ADK? ............................................................. ............ ...... 7
3.2 How to Use Lua in Target Mode?................................... ............................... ............ .......... 8
3.3 How to Use Lua in Remote Mode? ........... ............ ............................... ............ ................... . 9
3.4 How to Debug the Lua File? .. ............ ............................... .................................... ..............9
4 Creating Lua Scripts........................................................................................................... 10
4.1 How does the Lua ADK Event System Work? .. .................................... ............................... .. 10
4.2 Example Applications................ ............................... ............ ................... ............ ............ 11
5 Lua API Function and Module Reference......................................................................... 12
5.1 Lua Callback Functions Called from C .................. ............ ................................................... 12
5.1.1 Function 'initialize' ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ..... . 12
5.1.2 Function 'loop' ...... . . . ...... . . . ..... . . . . ..... . . . . ..... . . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . . 12
5.1.3 Function 'on_can' ... . . . ...... . . . ...... . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ..... . . . ...... . . . ...... . . . ...... . . . . 12
5.1.4 Function 'on_mqtt' .... . . . . ...... . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . 12
5.2 C Functions Called from Lua ......................... ................... ............ ............................... ...... 13
5.2.1 Module 'misc' .. ...... . . . ...... . . . ..... . . . . ...... . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . . . . 13
5.2.2 Module 'can' ...... . . . ...... . . . ..... . . . . ...... . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . . . . .... 14
5.2.3 Module 'mqtt' . ...... . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ..... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . . 15
5.2.4 Module 'sys' . . ...... . . . ..... . . . . ...... . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . . . . ...... . . ... 15
5.2.5 Module 'json' ..... . . . ...... . . . ..... . . . . ...... . . ...... . . . . ..... . . . ...... . . . ...... . . . ...... . . . ...... . . . ..... . . . . .... 17
5.2.6 Module 'array'.... . . . . ..... . . . ...... . . . . ..... . . . ...... . . . ...... . . . ..... . . . . ...... . . . ..... . . . . ...... . . ...... . . . . ... 17
A Lua License......................................................................................................................... 21
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
This page intentionally left blank
Purpose of this Document 3 (22)
1 Purpose of this Document
The Lua ADK FAQ answers common questions concerning the development of Lua applications
for Ixxat CAN@net NT and CANbridge NT.
For information how to program in Lua, refer to Lua resources on the internet:
• complete language specification in the Lua Reference Manual on lua.org
• information about availability and licensing issues in the lua.org FAQ
• Q and A content and help for learning Lua as a second language in the unofficial Lua FAQ
• Lua Users Wiki provides examples source and relevant discussions, and information to start
Learning Lua
• Programming in Lua by Roberto Ierusalimschy, one of the creators of Lua, is a detailed
introduction to Lua programming. The online version is the first edition and aims at. Lua 5.0.
The third edition for Lua 5.3 is available for purchase.
This FAQ is derived from the FAQ of the NodeMCU 3.0.0 framework, published under the license
©
MIT
zeroday)/nodemcu.com. This original FAQ was started by Terry Ellison as an unofficial FAQ
in mid 2015. This version in October 2019 includes some significant rewrites.
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
Description of Ixxat Lua ADK 4 (22)
2 Description of Ixxat Lua ADK
The Ixxat Lua ADK is based on the standard Lua 5.3.5 distribution, a fully featured
implementation of Lua 5.3. The implementation is optimized for embedded system development
and execution to provide a scripting framework that can be used to deliver useful applications
within the limited RAM and Flash memory resources of embedded processors.
• All standard Lua language constructs and data types are working.
• Main Lua standard libraries core (partly), coroutine, string, math, debug and
table are implemented.
• File handling functions like require, dofile, and loadfile are missing. To be able to
load other Lua files, like json.lua and misc.lua, the sys library provides the dofile
function that is similar to the original functions.
2.1 Difference between Standard Lua and Ixxat Lua ADK
Lua is primarily an extension language that makes no assumptions about a main program. Lua
works embedded in a host application to provide a powerful, lightweight scripting language for
use within applications. The host application can invoke functions to execute a piece of Lua code,
can write and read Lua variables, and can register C functions to be called by Lua code. Through
the use of C functions, Lua can be augmented to cope with a wide range of different domains,
thus creating customized programming languages that share a syntactical framework.
The Ixxat Lua ADK is a firmware extension and must be layered over the standard firmware. The
hooks and features of Lua enable the Ixxat Lua ADK to be seamlessly integrated without losing
any of the standard Lua language features. The firmware has replaced some standard Lua
modules that do not align well with the firmware. For example, the standard io and os libraries
do not work, but are partly replaced by the libraries can, mqtt, and sys. To write to the
terminal window that is provided by the CAN-Gateway Configurator the function
print(string) is used by default.
The main impacts of the Ixxat Lua ADK are how application programmers must approach the
developing and structuring of their applications. The ADK is nonpreemptive and event driven.
Tasks can be associated with given events by using the ADK API to registering callback functions
to the corresponding events. Events are queued internally within the ADK, and then the
associated tasks are called one at a time. Each task returns the control to the ADK when run to
completion (finished successfully).
The ADK libraries act as C wrappers around registered Lua callback functions to enable these to
be used as ADK tasks. Therefore an event-driven programming style must be used in writing Lua
programs.
2.2 Lua Library Functions Enabling the Registration of Lua Callbacks
The following library functions define or use callbacks:
• sys.call_after() in Lua module sys
• can.register_msg() in Lua module can
• mqtt.subscribe() in Lua module mqtt
For can the standard Lua callback function on_can is used and for mqtt the standard Lua
callback function on_mqtt.
The libraries (can , sys, mqtt, etc.) use the ADK callback mechanism to bind Lua processing to
individual events (for example a CAN message reception). Developers should make full use of
these events to keep Lua execution sequences short.
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
Description of Ixxat Lua ADK 5 (22)
For more information see the module documentation in Lua API Function and Module Reference,
p. 12.
2.3 Limitations of the Ixxat Lua ADK
The Ixxat Lua ADK has hardware resource limitations because code is loaded from the Flash file
system into off-chip RAM and executed there. This RAM area is shared between Lua and other
tasks on the target. The overall size is approximately 900 KByte. Therefore, Lua can use up to
approximately 600 KByte RAM for code and data.
The total amount of memory in use by Lua (in Kbytes) can be determined and written to the
terminal window of the CAN-Gateway Configurator with the following command:
print(collectgarbage("count"))
Keep in mind:
• Lua scripts need much more CPU time than compiled code written in C.
• Do as less as possible computation in Lua.
• Do the computation with the lowest possible frequency.
To reduce the effort for Lua:
• If possible use mapping tables and other features.
• Use the max_frequency feature for registered can messages to reduce the on_can call
frequency.
• Use the array.repack function to reassemble CAN message payload.
The needed CPU power can be monitored via the output in the status bar of the CAN-Gateway
Configurator. The Lua function sys.get_us_time() allows to measure execution times more
precisely.
A typical value for the execution time of a short Lua function is 150 to 200 μs. About 5000–8000
messages can be processed per second.
2.4 Specifics in Coding for the Ixxat Lua ADK
2.4.1 Bit Model 32 Bit Version
The Ixxat Lua ADK is compiled for the 32 bit model. Therefore integer and floating points values
are stored as 32 bit values instead of 64 bit values as with a standard desktop Lua installation.
2.4.2 Errors and Debugging
The Ixxat CAN@net/CANbridge NT runs the Lua ADK over the native hardware. There is an
underlying kernel system to capture errors and to provide graceful failure modes. To avoid
affecting the standard firmware, error handling is kept simple. If an error occurs when calling a
Lua function, an error message is written to the log file and Lua is stopped. Runtime errors in Lua
functions are written to the terminal and Lua is stopped. The rest of the firmware is running
without restrictions. To reactivate the Lua script the system has to be restarted.
There is currently no target debugging support. The print statement diagnostics through the
terminal interface of the system must be used. The Ixxat Lua ADK provides a remote debugging
feature to run the Lua script on the PC while communicating with the target device via an USB
connection.
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
Description of Ixxat Lua ADK 6 (22)
2.4.3 Declaring Variables
Two types of data can be assigned to Lua variables:
• values such as numbers, booleans, and strings
• references such as functions, tables, and user data
For example, if the contents of variable a are assigned to variable b, there is a difference
between values and references. In case of a value, the content of a is copied into b. In case of a
reference, both a and b now refer to the same object. No content is copied. The Ixxat Lua ADK
provides the function table.copy() which returns a deep copy of the provided table
parameters.
In standard Lua all variables can be classified as globals or locals. By default, any variable
that is referenced and not previously declared as local is global. Global variables persist in
the global table until the variable is explicitly deleted.
To see what global variables are in scope, use the following command:
for k,v in pairs(_G) do print(k,v) end
Local variables are lexically scoped. This means the scope of local variables is limited to the block
where they are declared. A block is the body of a control structure, the body of a function or a
chunk (the file or string with the code where the variable is declared). Any variable can be
declared local within nested blocks or functions without affecting the enclosing scope.
Because locals are lexically scoped it is also possible to refer to local variables in an outer scope.
These variables are still accessible within the inner scope.
The Lua runtime internally uses hashed key access to retrieve keyed data from a table. Locals are
stored as a contiguous vector and are accessed directly by an index, which is faster. Access to
firmware based tables is particularly slow.
Using locals as follows is both a lot faster at runtime and generates less byte code instructions
for their access:
local can_send = can.send
2.4.4 Passing Context between Lua Event Tasks
A single Lua function is bound to any event callback task. The function is executed from within
the relevant C code using a lua_call(). Each function can invoke other functions and so on.
But each function must ultimately return the control to the C library code which then returns the
control to the firmware.
Lua local variables that are defined inside a function only exist within the context of this
executing Lua function. Therefore locals are unreferenced on exit and any local data and garbage
might be collected between the lua_call() actions.
Context can be passed in two ways between event tasks:
• by global variables: any global variable persists until it is explicitly dereferenced by assigning
nil to the variable.
• by local variables: local variables that are defined in an outer scope (see description of locals
in Declaring Variables, p. 6).
CAN@net NT/CANbridge NT User Manual
4.02.0332.20002 1.2 en-US
Loading...