Scripts

Introduction

Code is wrritten in Lua, which is a lightweight, high-level programming language designed for embedded use, known for its simplicity and efficiency. Created in Brazil in 1993, it features dynamic typing, first-class functions, and a powerful table data structure, making it versatile for various applications. Lua is widely used in game development for scripting game logic, as well as in embedded systems and applications due to its extensibility and small footprint, allowing developers to easily integrate it with other languages and platforms.

LUA 5.1 Manual

How It Works

To extend Oktopus capabilities and adress the most diverse possible use cases we opted to use a scripting language on top of the actual code, so the gopher-lua library provides Go APIs that allows to easily embed LUA scripts to Go programs.

The Go software can interact to the LUA script and vice-versa. That way, it's possible to pass functions, parameters and events through both USP Controller/ACS and the user created automations.

Core Concepts

A "custom function", is as a function called from LUA which translates to a Go function that can interact with NATS, MongoDB, USP Controller, TR-069 ACS and all the other components of the software stack.

The "custom functions" will be detailed above in the next topics as just "functions" and separated into domain areas. We hope to provide usefull examples, and the limitation is on each person creativity.

Functions

send_usp_message()

Params:

1. Serial Number [string]

   The CPE unique identifier.

2. JSON payload [string]

   Request body to be sent to the CPE. Current supported bodies are : - Get - Set

Return:

• If the usp message generates an error:

• In the case of a successful transaction each key of the table will correspond to one of the parameters requested in the payload.

Example:

send_cwmp_message()

Params:

1. Serial Number [string]

   The CPE unique identifier.

2. XML payload [string]

   Request body to be sent to the CPE.

3. Message Type [integer]

   CWMP message type. 0 = getParameterValues 1 = setParameterValues 2 = addObject 3 = deleteObject 4 = getParameterNames

Return:

The data returned depends on the TR-069 message type:

• If the CWMP message generates an error:

• If it is a read or add operation the function will return a table.

• If it is a delete or set operation the data returned will be a boolean indicating if the result was a success or failure.

Example:

send_cwmp_async_message()

Works the same way as the send_cwmp_message() function, but does not use the CWMP Connection Request mechanism, which means this RPC will only reach the CPE in the next Inform event of it. This allows to reach CPEs behind NAT, although it takes longer for the RPC to reach and be processed by the device.

listen_to_cwmp_event()

Listen to TR-069 events as defined in the standard.

Params:

1. Event [string] (optional) Possible events:

   If no value is set or the value is "*", than it listens to all events.

2. Serial Number [string] (optional) CPE unique identifier. If it's not set or the value is "*", then it listens to all CPEs event(s).

3. Callback function (required)

4. Number of events to process in parallel [integer] (optional)

5. Discard if processing [boolean] (optional) When true, an incoming event for a device that already has an event being processed (i.e. still running the callback) is discarded instead of waiting for a free worker slot. Useful to avoid piling up stale events for a slow or unresponsive device. Defaults to false, which queues the event until a worker slot frees up.

Return:

Example:

To process up to 10 events concurrently, and discard new events arriving for a device that's still being processed:

get_device()

Get device attributes from its unique identifier.

Params:

1. Serial Number [string]

   The CPE unique identifier.

Return:

If the CPE was not found in the database the function returns a boolean with false value. In case the CPE is found it returns a table with all attributes:

data_model reflects the CWMP root data model reported by the CPE, either "TR-098" (InternetGatewayDevice.) or "TR-181" (Device.); it is empty for USP-only devices.

Example:

listen_to_new_device()

Receive all new device attributes that connect to Oktopus, independent of the protocol.

Params:

1. Callback function with new device data

Example:

sleep()

Blocks the code execution for certain time.

Params:

1. Time duration [integer] Seconds of blocking the code execution.

Example:

create_or_update_device_credential()

Params:

1. Username [string]

2. Password [string]

Return:

Bool value indicating true if the operation was successfull or false if there was an error.

Example:

generate_random_string()

Params:

1. Length [int] Size of the string to be generated

Example:

delete_device()

Remove device from database.

Params:

1. Serial Number [string]

   The unique identifier of the CPE to be removed.

Return:

Bool value indicating true if the operation was successfull and the device was removed from database or false if there was an error.

Example:

set_device_model()

Update the model attribute of a device in the database.

Params:

1. Serial Number [string]

   The CPE unique identifier.

2. Model [string]

   The new model value to set.

Return:

Bool value indicating true if the operation was successfull or false if there was an error.

Example:

get_all_devices()

Retrieve all devices saved on the database.

Return:

List of device objects.

Example:

refresh_device_parameters()

Sync device saved parameters, as PPPoE user, IP address and WAN MAC.

Params:

1. Serial number / USP agent endpoint id [string] The unique identifier of the CPE to be removed.

Return: Bool value indicating f the operation was successfully executed ot not.

Example:

http_request()

Make an HTTP call to a third-party REST API to gather or send data. Useful for integrating scripts with external systems (billing, ticketing, monitoring, etc).

Only http/https URLs are accepted; URLs with embedded credentials (e.g. http://user:pass@host/) are rejected; this function can only reach external/public hosts.

Params:

1. Method [string]

   HTTP method, e.g. "GET", "POST", "PUT", "PATCH", "DELETE". Defaults to "GET" if empty.

2. URL [string]

   Full request URL. Must start with http:// or https://.

3. Headers [table] (optional)

   Table of header name/value pairs to send with the request.

4. Body [string] (optional)

   Request body. Commonly used with POST/PUT/PATCH. Use json_encode() to build a JSON body.

Return:

A table is always returned:

• ok is true when the request completed with a 2xx status code.

• error_message is populated when the request could not be completed at all (invalid URL, blocked target, timeout, connection error) — it does not mean the remote API returned an HTTP error.

• Use body together with json_decode() to parse JSON responses.

Example:

json_decode()

Parse a JSON string into a Lua table (or scalar value). Commonly used to read the body returned by http_request().

Params:

1. JSON string [string]

Return:

Two values are returned: the decoded value (table, string, number, boolean or nil), and an error message [string] that is nil when decoding succeeds.

Example:

json_encode()

Convert a Lua table (or scalar value) into a JSON string. Commonly used to build the body sent through http_request().

Params:

1. Value [table, string, number or boolean]

Return:

Two values are returned: the encoded JSON [string], and an error message [string] that is nil when encoding succeeds.

Example:

get_service_instances()

List the service instances attached to a device.

Params:

1. Serial Number [string]

   The CPE unique identifier.

Return:

A table with ok [boolean], error_message [string], error_code [number] and, on success, instances [table] — an array of tables, each with id, device_id, service_id, status and variables:

Example:

create_service_instance()

Attach a service definition to a device, creating a new service instance.

Params:

1. Serial Number [string] — the CPE unique identifier.

2. Service Definition ID [string].

3. Variables [table, optional] — the service-specific variable values for this device.

Return:

A table with ok [boolean], error_message [string] and error_code [number]. The created instance's id is not returned — call get_service_instances() to look it up.

Example:

edit_service_instance()

Replace an existing service instance's device and variables. The service definition id cannot be changed.

Params:

1. Service Instance ID [string].

2. Serial Number [string] — the CPE unique identifier.

3. Service Definition ID [string] — must match the instance's current service definition.

4. Variables [table, optional] — the new service-specific variable values.

Return:

A table with ok [boolean], error_message [string] and error_code [number].

Example:

delete_service_instance()

Delete a service instance.

Params:

1. Service Instance ID [string].

Return:

A table with ok [boolean], error_message [string] and error_code [number].

Example:

apply_service_instance()

Run a service instance's provisioning script against its device right away, instead of waiting for its trigger event (see Manual Execution).

Params:

1. Service Instance ID [string].

Return:

A table with ok [boolean], error_message [string], error_code [number] and, on success, status [string] ("provisioned" or "failed"). ok reflects whether the request itself succeeded; status is the actual provisioning outcome — a script can legitimately fail provisioning even though the request succeeded (ok = true, status = "failed").

Example:

apply_service_instance_and_forget()

Trigger a service instance's provisioning script the same way apply_service_instance() does, but don't wait for it to run to completion — the request is enqueued and the function returns immediately. Because it doesn't wait for a response, it can't report the final status, and ok only reflects whether the message was enqueued locally, not whether the zero-touch-provisioning service actually received or ran it.

Use this when applying a service instance whose script may run long (e.g. it calls sleep() or does several sequential CPE round trips) and the caller doesn't need to wait for the outcome.

Params:

1. Service Instance ID [string].

Return:

A table with ok [boolean], error_message [string] and error_code [number]. There is no status field.

Example: