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 cgfrom esphome.components import socketimport esphome.config_validation as cvfrom esphome.components.const import CONF_HOST, CONF_ROLEfrom 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_LISTENERsocket::TcpListener listener_;#endif#ifdef USE_SOCKET_IPV4_ALLOWvoid 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.
Several Links
Section titled “Several Links”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.
Copyright © 2026 ESPHome - A project from the Open Home Foundation