Link Search Menu Expand Document

I/O API

I/O on Libertas-OS is strictly network I/O.

File I/O is forbidden. Data access is formalized in Data API with strong data protection.

I/O API is reactive only.

Data Types

lbuffer

Lua does not have a built-in buffer support. We use lbuffer with our I/O API.

All I/O write calls support lbuffer as an input parameter, along with string.

I/O read calls can take lbuffer as input.

Read the class lbuffer for API documentation.

All network write APIs take either a string or lbuffer as part of the input. We defined the type alias below:

type LibertasNetData = string | lbuffer;

Type Aliases

type LibertasFd = number;

type LibertasHttpHeader = [name: string, value: string];

Enums

LibertasNetErrorType

Interface

LibertasHttpResponse

Callbacks

type LibertasNetDataCallback = (tag: any, fd: LibertasFd, data: string, addr?: string) => void;

type LibertasNetHttpCallback = (tag: any, fd: LibertasFd, data: LibertasHttpResponse) => void;

type LibertasNetErrorCallback = (tag: any, fd: LibertasFd, errorType: LibertasNetErrorType, errorCode: number, errorText: string) => void;number, errorText: string) => void;

Device Wake-on-Lan

This API sends a “wake-on-lan” UDP command to a LAN device.

Libertas_IoDeviceWakeOnLan

Net API

Create Network Socket

Libertas_NetNewTcp

Libertas_NetNewUdp

Libertas_NetNewHttp

Close & Clean Up

Libertas is designed for IoT. The usage pattern is a small, fixed amount of persistent network connections.

The design encourages the reuse of network sockets. Once the socket is closed, Thing-App can reuse the socket by calling connect API again on the same socket.

Libertas_NetClose

The socket and resources will be cleaned up by calling:

Libertas_NetDestroy

Connect

Libertas_NetConnect

Libertas_NetConnectDevice

Libertas_NetSetConnectTimeout

Read and Write

Reading

Use the APIs below to register the callback function. When there is incoming data, the callback function will be called.

Libertas_SetOnNetData

Libertas_SetOnNetHttpResponse

Writing

For a connected socket, the socket can only be written once it is ready. Use Libertas_SetOnNetReady to register the ready callback function. Initial write shall be made in this function.

Use the API below to write to a socket.

Libertas_NetWrite

Libertas_NetWriteUdp

Libertas_NetHttpAddRequest

The outgoing data will be queued internally. A callback function is called when all the data is written to the peer. Use Libertas_SetOnNetDrain to register the callback function.

Connected and Ready Events

As mentioned above, the socket can only be written once it is ready. For a plain TCP socket, it is ready when it is connected. So, the “ready” callback is called immediately after the “connected” callback.

However, once a TLS socket is connected, the peers must exchange data to establish an encrypted secure channel. It is called the handshake process. So “ready” will be fired later. If there is any error during the handshake, an error will be fired instead.

Libertas_SetOnNetConnected

Libertas_SetOnNetReady

Error Handling

Register the callback of network error. Please note that the error callback must be registered immediately after creating the socket.

Libertas_SetOnNetError

Timeouts

If the socket takes too long to finish reading or writing, we typically assume the socket is dead. There are two callbacks for read and write timeouts.

Libertas_SetOnNetReadTimeout

Libertas_SetOnNetWriteTimeout

Other Callbacks

Libertas_SetOnNetClosed

Libertas_SetOnNetDestroyed

Libertas_SetOnNetLookup