Skip to content

TCP listener

socket::TcpListener is the server half next to the TCP client link. The header is esphome/components/socket/tcp_listener.h, and the implementation is tcp_listener.cpp. It is compiled only when a component calls socket.require_tcp_listener(). That call also pulls in the client link and the IPv4 resolver.

The listener owns the listen socket and, when the config passes a list, an IPv4 allow list. poll() accepts one peer at a time and adopts the socket into the caller’s TcpClientLink. A second connection waits in the stack until the first one drops. The listen backlog is 1 unless the caller passes another to poll_listen().

uart_tcp is the first caller; tcp_uart’s server role (esphome#20026) follows. A server role calls require_tcp_listener() and, for a non-empty allowed_ips, add_ipv4_allow. An empty or omitted list does not compile the allow list, and every peer is accepted. consume_role_sockets accounts for one stream socket, plus one listen socket when role is server:

BASE_SCHEMA holds the options both roles share. An omitted list is fine; add_ipv4_allow accepts None.

import esphome.codegen as cg
from esphome.components import socket
import esphome.config_validation as cv
from esphome.components.const import CONF_HOST, CONF_ROLE
from esphome.const import CONF_ID
AUTO_LOAD = ["socket"]
CONF_ALLOWED_IPS = "allowed_ips"
CONFIG_SCHEMA = cv.All(
cv.typed_schema(
{
"client": BASE_SCHEMA.extend({cv.Required(CONF_HOST): cv.string}),
"server": BASE_SCHEMA.extend(
{cv.Optional(CONF_ALLOWED_IPS): socket.IPV4_ALLOW_SCHEMA}
),
},
key=CONF_ROLE,
default_type="client",
lower=True,
),
socket.consume_role_sockets("my_component"),
)
async def to_code(config):
var = cg.new_Pvariable(config[CONF_ID])
await cg.register_component(var, config)
if config[CONF_ROLE] == "server":
socket.require_tcp_listener()
cg.add(var.set_server(True))
socket.add_ipv4_allow(var.set_allow, config.get(CONF_ALLOWED_IPS), config[CONF_ID])
else:
socket.require_tcp_client_link()

set_allow and the member behind it exist only under USE_SOCKET_IPV4_ALLOW, which add_ipv4_allow defines when it emits entries, so guard any direct use the same way.

Call begin() from setup() with the log tag. Call poll() once per loop, and close() from on_shutdown(). poll() takes the link and a flag. Pass false to hold the next accept until the component has handled the disconnect edge, so a sensor and any stale bytes still see the drop.

socket::TcpClientLink link_;
bool server_{false};
// The link state loop() saw last; the edge clears buffers and publishes sensors.
bool link_was_up_{false};
#ifdef USE_SOCKET_TCP_LISTENER
socket::TcpListener listener_;
#endif
#ifdef USE_SOCKET_IPV4_ALLOW
void set_allow(const socket::Ipv4AllowEntry *entries, size_t count) {
this->listener_.set_allow(entries, count);
}
#endif
void setup() override {
this->link_.begin(TAG);
#ifdef USE_SOCKET_TCP_LISTENER
this->listener_.begin(TAG);
#endif
}
void loop() override {
#ifdef USE_SOCKET_TCP_LISTENER
if (this->server_) {
// Hold the accept until the previous drop's edge has run.
this->listener_.poll(this->link_, !this->link_was_up_);
} else
#endif
{
this->link_.poll();
}
if (this->link_.connected() != this->link_was_up_) {
this->link_was_up_ = this->link_.connected();
// The disconnect edge: clear component state, publish sensors.
}
}

A rejected peer is closed without being adopted, and the warning is logged at most once every 5 seconds. Call the listener’s dump_config() from the component’s own dump_config(); it prints one line per allowed network. EAGAIN, EWOULDBLOCK, ECONNABORTED and EINTR from accept() are ignored. Running out of sockets or memory (ENFILE, EMFILE, ENOBUFS, ENOMEM) is not logged and keeps the listen socket. Any other accept error closes the listen socket; poll() reopens it after the link’s reconnect interval.

A server with several connections on one port keeps one TcpClientLink per connection and calls the two steps of poll() itself. poll_listen(link) opens the listen socket on the port and reconnect interval of link, one of the links, and returns true when a connection waits. Call accept(link) right after poll_listen() returned true. It returns the accepted socket, or nullptr when none was waiting, the allow list rejected the peer or the accept failed. A listener error closes the listen socket as above, and poll_listen() reopens it after link’s reconnect interval. The caller picks the link that adopts the socket.

if (this->listener_.poll_listen(this->links_[0], this->links_.size())) {
auto sock = this->listener_.accept(this->links_[0]);
if (sock != nullptr) {
// A link that is down and whose disconnect edge has run. When all links are in use, close
// one and run its edge first.
this->free_link_().adopt(std::move(sock));
}
}

Pass the number of links to poll_listen() as the backlog, so that connections that arrive together can wait for accept().

Instead of the one stream socket above, a server counts one stream socket per connection when consume_role_sockets gets the config key that holds the number of connections as its second argument. It still counts a single listen socket in all, because the links share the one listener:

from esphome.const import CONF_MAX_CONNECTIONS
socket.consume_role_sockets("my_component", CONF_MAX_CONNECTIONS)

The server schema must give that key a default, for example cv.Optional(CONF_MAX_CONNECTIONS, default=1), because consume_role_sockets reads it without a fallback.