Functions

Base Library

The library functions of the base library are detailed by the following table. Make sure you read the purple ‘Note’ at the bottom of this page, regarding the ‘import' function.

Import

Function

Description

import

Import function from base library (ARG1: <base library function>).

Import function from non-base library (ARG1: <library>, ARG2: <library function>). For example:

LUA

$ import("set_io_type_cfg")

I/O Config

Function	Description
set_io_type_ cfg	Configure I/O (ARG1: PIN<x>) as type (ARG2: NONE, GPIO_OUT, GPIO_IN, PWM, UART_OUT, UART_IN, SPI_OUT, SPI_IN or I2C).
reset_io_type_ cfg	Reset I/O (ARG1: PIN<x>) to type NONE.
reset_all_io_ type_cfg	Reset all I/O to type NONE (no arguments). For example: LUA `$ reset_all_io_type_cfg()`

GPIO

Function	Description
set_gpio	Set I/O (ARG1: PIN<x>), configured as GPIO_OUT, to level (ARG2: LOW, HIGH or TOGGLE). For example: LUA `$ set_gpio(PIN7, HIGH)`
get_gpio	Get I/O (ARG1: PIN<x>), configured as GPIO_IN, level. For example: LUA `$ my_kite = get_gpio(PIN2) $ if my_kite == HIGH then print(" my_kite is HIGH!") $$ else print("my_kite is not HIGH!") end my_kite is HIGH!`

PWM

Function	Description
set_pwm	Set I/O (ARG1: PIN<x>), configured as PWM, to duty cycle (ARG2: 0 - PWM_MAX). The value of ‘PWM_MAX’ is 256 (100% duty).

SPI

Function	Description
spi_tx	Same as 'spi_tx_byte'. The behavior in the case the ARG1 I/O PIN is configured to have a non byte-multiple data width: If the data width, X, is less than one byte, each byte that is sent to the SPI module will have the most-significant [8 - X] bits discarded, the remainder are transmitted. If the data width, X, is greater than one byte, each byte that is sent to the SPI module is buffered until a byte-multiple of data is stored. Then the most-significant [Buffered-Bits - X] bits are discarded, the remainder are transmitted.
spi_tx_byte	Send 1 byte (ARG2: integer) of data to the I/O (ARG1: PIN<x>), configured as SPI_OUT. It is possible this will NOT result in an actual SPI transmission (if it is less than the build configured number of bits per SPI transmission). See description of ‘spi_tx’.
spi_tx_char	Send 1 byte (ARG2: string) of data to I/O (ARG1: PIN<x>), configured as SPI_OUT.
spi_tx_int	Send 4 bytes (ARG2: integer) of data to I/O (ARG1: PIN<x>), configured as SPI_OUT. It is possible this will result in multiple SPI transmissions.
spi_rx_byte	Receive one byte from I/O (ARG1: PIN<x>), configured as SPI_IN. This function will hang if no SPI data has been received.
spi_rx_byte_ nonblocking	Not included in Beta Release.
spi_rx_char	Receive one character from I/O (ARG1: PIN<x>), configured as SPI_IN. This function will hang if no SPI data has been received.
spi_rx_char_ nonblocking	Not included in Beta Release.

UART

Function	Description
uart_tx	Same as 'uart_tx_byte'. For example: LUA `$ uart_tx(PIN4, 0x30)`
uart_tx_char	Send 1 byte (ARG2: string) of data to the I/O (ARG1: PIN<x>), configured as UART_OUT.
uart_tx_byte	Send 1 byte (ARG2: integer) of data to the I/O (ARG1: PIN<x>), configured as UART_OUT.
uart_tx_int	Send 4 bytes (ARG2: integer) of data to the I/O (ARG1: PIN<x>), configured as UART_OUT.
uart_rx_byte	Receive and return 1 byte (as an integer) of data from the I/O (ARG1: PIN<x>), configured as UART_IN. This function will block if the corresponding UART module currently has no data, until a byte of data is received.
uart_rx_byte_ nonblocking	Receive and return 1 byte (as an integer) of data and return 'byte valid' from the I/O (ARG1: PIN<x>), configured as UART_IN. This function will not block - if the corresponding UART_IN module currently has no data then 'byte valid' will be false.
uart_rx_char	Same as 'uart_rx_byte', however the returned UART data will be a character.
uart_rx_char_ nonblocking	Again, same as 'uart_rx_byte_nonblocking', however the returned UART data will be a character.

I2C

Function	Description
i2c_tx	Not included in Beta Release.
i2c_tx_char	Not included in Beta Release.
i2c_tx_byte	Not included in Beta Release.
i2c_tx_int	Not included in Beta Release.
i2c_rx_byte	Not included in Beta Release.
i2c_rx_byte_ nonblocking	Not included in Beta Release.
i2c_rx_char	Not included in Beta Release.
i2c_rx_char_ nonblocking	Not included in Beta Release.

FPGA Bus

Function	Description
fpga_write	Write a integer (ARG1: integer) to the FPGA bus. Block until the FPGA bus ‘ready’ strobe is asserted.
fpga_write_nonblocking	Attempt to write a integer (ARG1: integer) to the FPGA bus. Doesn’t block, returns true / false to indicate if the write was successful (i.e. the FPGA bus ‘ready’ strobe was asserted).
fpga_read	Read a integer from the FPGA bus. Block until the FPGA bus ‘ready’ strobe is asserted.
fpga_read_nonblocking	Read a integer from the FPGA bus. Doesn’t block, returns the value read (0 in invalid) and true / false to indicate if the read was successful (i.e. the FPGA bus ‘ready’ strobe was asserted).

Interrupt

Function	Description
global_ interrupt_ enable	Global interrupt enable. The 'interrupt' function will trigger if an enabled interrupt to occurs (no arguments).
global_ interrupt_ disable	Global interrupt disable. The 'interrupt' function will not trigger even if an enabled interrupt to occurs (no arguments).
repl_ interrupt_ mode_enable	This interrupt mode is enabled by default prior to the execution of each new atomic (i.e. single or set of multi-line) REPL input. It is disabled by default prior to the execution of a program. Thus only a multi-line REPL input, which calls ‘repl_interrupt_mode_disable' will proceed with this mode disabled, and only a program which calls ‘repl_interrupt_mode_enable’ will proceed with this mode enabled (from the point at which it is enabled / disabled, of course). If enabled, any individual interrupt source that is enabled and active at the end of the entire REPL input will trigger an interrupt at that point (i.e. just prior to returning to user prompt). This is in addition to the typical interrupt functionality of triggering between each line of script (i.e. in the case of a REPL, a multi-line REPL input). Also, if the interrupts have been enabled globally (i.e. 'global_interrupt_enable') this the global interrupt enable will persist across individual, atomic calls to the REPL (i.e. across single-line calls, or separate multi-line calls). Otherwise, the global interrupt configuration will be reset to disabled at the beginning of each new input into the REPL (i.e. a single-line or multi-line input has completed, and the user has been prompted to enter new Lua script).
repl_ interrupt_ mode_disable	See above description.
set_interrupt_ types_for_pin	Enable only specified interrupts by bitmask (ARG2: bit-wise combination of <PIN<x> Type>_INTRPT_<type>) for input I/O (ARG1: PIN<x>). For example: LUA `$ set_io_config(PIN1, GPIO_IN) $ set_interrupt_types_for_pin(PIN1, GPIO_INTRPT_LOW \| GPIO_INTRPT_RISING_EDGE \| GPIO_INTRPT_FALLING_EDGE) $ print("Enabled Interrupt Types of 'Low' 'Rising Edge' and 'Falling Edge' for GPIO_IN PIN1") Enabled Interrupt Types of 'Low' 'Rising Edge' and 'Falling Edge' for GPIO_IN PIN1`
enable_ interrupt_ types_for_pin	Same as 'set_interrupt_types_for_pin' however additionally enable specified interrupts, as well as whatever is already enabled.
disable_ interrupt_ types_for_pin	Disable specified interrupts by bitmask (ARG2: bit-wise combination of <PIN<x> Type>_INTRPT_<type>) for input I/O (ARG1: PIN<x>).
get_ interrupts_ on_pin	Get interrupt vector for I/O (ARG1: PIN<x>).
ack_interrupt_ types_on_pin	Acknowledge specified interrupts by bitmask (ARG2: bit-wise combination of <PIN<x> Type>_INTRPT_<type>) for I/O (ARG1: PIN<x>).
ack_interrupt_ types_on_pins	Acknowledge specified interrupts by bitmask (ARG2: bit-wise combination of <PIN<x> Type>_INTRPT_<type>) for I/O specified by bitmask (ARG1: PIN<x>_BITMASK).
interrupt_ handler	Users redefine this function with a single argument, 'interrupt_vector', and it will be called upon an enabled interrupt occurring. When called, the 'interrupt_vector' argument will reflect all PIN<x> upon which an interrupt occurred, via the corresponding 'PIN<x>_BITMASK'. For example: LUA `$ set_interrupt_types_for_pin(PIN4, GPIO_INTRPT_LOW \| GPIO_INTRPT_RISING_EDGE) $ set_interrupt_types_for_pin(PIN6, GPIO_INTRPT_FALLING_EDGE) $ global_interrupt_enable() $ function interrupt_handler(interrupt_vector) if (interrupt_vector & PIN4_BITMASK) ~= 0 then print("Interrupt occurred on PIN4!") end if (interrupt_vector & PIN6_BITMASK) ~= 0 then print("Interrupt occurred on PIN6!") end end interrupt.bind(interrupt_handler)`

Sleep

Function	Description
sleep	Pause for X (ARG1: integer) seconds. Interruptible.
sleep_f	Pause for X (ARG1: float) seconds. Interruptible.
msleep	Pause for X (ARG1: integer) milliseconds. Interruptible.
msleep_f	Pause for X (ARG1: float) milliseconds. Interruptible.
usleep	Pause for X (ARG1: integer) microseconds. Interruptible.
sleep_noint	Pause for X (ARG1: integer) seconds. Uninterruptible.
mssleep_noint	Pause for X (ARG1: integer) milliseconds. Uninterruptible.
usleep_noint	Pause for X (ARG1: integer) microseconds. Uninterruptible.

Watchdog

Function

Description

watchdog_reset

Reset the hardware watchdog back to its start timer value. See Command Mode for more information. If the watchdog is not present, calling this function will have no effect.

get_watchdog_

timer

Get the current watchdog timer value. See Command Mode for more information. If the watchdog is not present, calling this function will return zero.

Core Communication

Function	Description
pipe_tx_byte	Send 1 byte (ARG2: integer) of data to CORE (ARG1: PIN<x>), blocking if the channel is currently busy (i.e. the FIFO is full). Attempts to send data to self will throw an error. The xbar data route must be enabled in the build configuration of the XBar, or the function will hang - see Command Mode for more information. For example: LUA `[ #1 ] $ pipe_tx_byte(CORE2, 0xde) [ #1 ] $ pipe_tx_byte(CORE3, 0xad) [ #1 ] $ pipe_tx_byte(CORE4, 0xbe) [ #1 ] $ pipe_tx_byte(CORE1, 0xef) stdin:1: bad argument #1 to 'pipe_tx_byte' (invalid core number) stack traceback: [C]: in function 'pipe_tx_byte' stdin:1: in main chunk`
pipe_tx_byte_ nonblocking	Attempt to send 1 byte (ARG2: integer) of data to CORE (ARG1: PIN<x>), will not block if the channel is currently busy (i.e. the xbar data FIFO is full). Returns an integer representing the number of bytes sent. The route must be enabled in the build configuration of the XBar, or the function will hang.
pipe_rx_byte	Receive 1 byte (ARG2: integer) of data from CORE (ARG1: PIN<x>), blocking if the channel is currently busy (i.e. the FIFO is empty). Attempts to send data to self will throw an error. The xbar data route must be enabled in the build configuration of the XBar, or the function will hang.
pipe_rx_byte_ nonblocking	Attempt to receive 1 byte (ARG2: integer) of data from CORE (ARG1: PIN<x>), will not block if the channel is currently busy (i.e. the xbar data FIFO is full). Returns an integer representing the number of bytes received, and the actual byte received (zero if none received). The route must be enabled in the build configuration of the XBar, or the function will hang.

Core Synchronization

Function	Description
lock	Lock xbar barrier between Core<self> and Core <x> (ARG1: integer). Will block until barrier is unlocked by Core<x>. On power-on, all xbar barriers will begin in the ‘unlocked’ state, to the depth listed in the Xbar config (see Command Mode).
lock_ nonblocking	Attempt to lock xbar barrier between Core<self> and Core <x> (ARG1: integer). Will not block if barrier has not been unlocked by that Core. Returns ‘1' to represent successful locking of the barrier, '0’ otherwise.
unlock	Unlock xbar barrier between Core<self> and Core <x> (ARG1: integer). Will block until barrier is locked by Core<x>.
unlock_ nonblocking	Attempt to unlock xbar barrier between Core<self> and Core <x> (ARG1: integer). Will not block if barrier has not been locked by Core<x>. Returns ‘1' to represent successful unlocking of the barrier, '0’ otherwise.

Program

Function

Description

run_program

Run the program named (ARG1: string). For example:

LUA

$  cmd
/ list|programs
	Program 1.	: hello_world.lua
	Program 2.	: the_day_my_bum_went_psycho.lua  
	Program 3.	: gpio_example.lua
/ exit
$ run_program("the_day_my_bum_went_psycho.lua")
This is the story of the day my Bum went Psycho.
..actually forget it. Program end.

Power

Function	Description
reboot	Reboot the current Core.
exit	Exit the current program or statement (REPL), , irrespective of nested program level. If provided, returns argument 1, of any type (ARG1: obj).

By default, all functions except ‘reboot’, ‘exit’ and ‘import’ need to be first imported prior to being called. This is by design, in order to reduce memory usage.

It is possible to import the entire API in a single call to ‘import(“all”).’

Interrupt Library

Function	Description
bind	Bind the interrupt handler (ARG1: function) to the global interrupt source. Is part of the interrupt library, so must be called as such: LUA `$ interrupt.bind(interrupt_handler)`
call	Explicitly call the interrupt handler that is bound to the global interrupt source. Is part of the interrupt library, so must be called as such: LUA `$ interrupt.call()`

Third-party Libraries

There is some support for the following built-in Lua libraries. Use the ‘import’ function, with the library name as the first argument, to import them.