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 LibertasHttpHeader = [name: string, value: string];
Enums
Interface
Callbacks
type LibertasNetDataCallback = (tag: any, fd: LibertasFd, data: string, addr?: string) => void;
type LibertasNetHttpCallback = (tag: any, fd: LibertasFd, data: LibertasHttpResponse) => void;
Device Wake-on-Lan
This API sends a “wake-on-lan” UDP command to a LAN device.
Net API
Create Network Socket
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.
The socket and resources will be cleaned up by calling:
Connect
Read and Write
Reading
Use the APIs below to register the callback function. When there is incoming data, the callback function will be called.
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.
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.
Error Handling
Register the callback of network error. Please note that the error callback must be registered immediately after creating the socket.
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.