API — TCP Sockets

Raw non-blocking TCP/TLS client sockets. Connections are handled cross-core by the Core 1 network stack. A static pool supports up to 4 simultaneous connections.

picocalc.tcp

Callbacks fire from the main loop — they are pumped by the firmware’s debug hook. Call picocalc.input.update() or picocalc.sys.sleep() regularly in your main loop so they can run.

Functions

picocalc.tcp.new(host [, port] [, use_ssl])

Open a new TCP connection to a host.

• Parameters:
  • host (string): Hostname or IP address
  • port (number, optional): Port number. Default 80.
  • use_ssl (boolean, optional): true for a TLS connection. Default false. TLS verifies the server certificate (OS root bundle + host name); a TLS connect before SNTP has set the clock fails with “clock not set”. The socket counts as connected only after the TLS handshake.
• Returns: a connection object, or nil, err when the 4-socket pool is full. Nothing is sent until conn:connect().

local conn = picocalc.tcp.new("example.com", 443, true)

---

Connection Methods

Objects returned by picocalc.tcp.new().

conn:connect()

Start connecting (non-blocking).

• Returns: true, or false, err (WiFi not available, already connecting or connected)

Completion: isConnected(), waitConnected(), the connect callback or picocalc.tcp.CB_CONNECT in getEvents().

---

conn:setInsecure(flag)

Before connect(): TLS without certificate verification or the clock check (self-signed development servers only). Default false.

---

conn:write(data)

Write data to the connection.

• Parameters:
  • data (string): Data to send
• Returns: (number) Number of bytes written, or -1 on error

conn:write("GET / HTTP/1.0\r\n\r\n")

---

conn:read([max_len])

Read available data from the connection.

• Parameters:
  • max_len (number, optional): Maximum number of bytes to read
• Returns: (string or nil) Data read, or nil if no data is available

local chunk = conn:read(1024)

---

conn:close()

Close the connection.

The object is unusable afterwards (I/O raises). Data already received stays readable until close, including after the peer closes.

• Parameters: None
• Returns: None

conn:close()

---

conn:available()

Get the number of bytes available to read.

• Parameters: None
• Returns: (number) Bytes available

if conn:available() > 0 then
    local data = conn:read()
end

---

conn:error()

Get the last connection error.

• Parameters: None
• Returns: (string or nil) Error string, or nil if there is no error

---

conn:isConnected()

Check whether the connection is established.

• Parameters: None
• Returns: (boolean) true if connected

---

conn:setConnectTimeout(seconds)

Set the connection timeout.

Applies to the next connect; default 15 s (covers the TLS handshake).

• Parameters:
  • seconds (number): Timeout in seconds
• Returns: None

conn:setConnectTimeout(10)

---

conn:setReadTimeout(seconds)

Set the read timeout.

Off by default; 0 disables it.

• Parameters:
  • seconds (number): Timeout in seconds
• Returns: None

---

conn:setConnectCallback(fn)

Set a callback fired when the connection is established (or fails). The callback receives the connection object.

Callbacks receive the socket and are never nested.

• Parameters:
  • fn (function): function(conn) ... end
• Returns: None

conn:setConnectCallback(function(c)
    picocalc.sys.log("connected")
end)

---

conn:setReadCallback(fn)

Set a callback fired when data arrives. The callback receives the connection object.

• Parameters:
  • fn (function): function(conn) ... end
• Returns: None

conn:setReadCallback(function(c)
    local data = c:read()
    if data then picocalc.sys.log("got " .. #data .. " bytes") end
end)

---

conn:setCloseCallback(fn)

Set a callback fired when the connection closes. The callback receives the connection object.

• Parameters:
  • fn (function): function(conn) ... end
• Returns: None

---

conn:getEvents()

Get pending connection events.

• Parameters: None
• Returns: (number) the pending events that have no callback registered, cleared by the call: picocalc.tcp.CB_CONNECT (1), CB_READ (2), CB_WRITE (4), CB_CLOSED (8), CB_FAILED (16).

---

conn:waitConnected([timeout_seconds])

Block until the connection is established.

• Parameters:
  • timeout_seconds (number, optional): Maximum time to wait
• Returns: (boolean) true if connected, false on timeout or failure

if conn:waitConnected(5) then
    conn:write("hello")
end

---

conn:waitData([timeout_seconds])

Block until data is available to read.

• Parameters:
  • timeout_seconds (number, optional): Maximum time to wait
• Returns: (boolean) true if data arrived, false on timeout

if conn:waitData(2) then
    local data = conn:read()
end