TCPClient
(inherits from Stream
via Client
)
Creates a client which can connect to a specified internet IP address and port (defined in the client.connect()
function).
Warning:
In most cases, using TCPClient
is not recommended. If you want to export data off your device, we recommend using Particle.publish()
and webhooks.
TCPClient
does not itself support HTTP. HTTP requires a 3rd-party library.- There is no https library for Particle devices, so you cannot connect to a TLS/SSL encrypted HTTP server. This means your data could be viewed, modified, or redirected as it crosses the Internet.
- Even if there were, doing a TLS/SSL authentication uses a large amount of data, up to 5 kilobytes per connection. The Particle cloud connection uses DTLS which is able to resume a session with much lower overhead and keep it alive for longer periods of time without having to re-authenticate.
- It is not possible to maintain TCP connections when the device is in sleep mode.
- Other protocols such as MQTT are not built-in and require 3rd-party libraries. We recommed using
Particle.publish()
and webhooks instead of MQTT. Using MQTT without TLS/SSL is not secure. Using MQTT with TLS/SSL will use large amounts of cellular data if also using sleep modes, as the MQTT connection cannot be maintained during sleep and each handshake requires 2 to 5 kilobytes of data.
// SYNTAX
TCPClient client;
// PROTOTYPE
int connect(IPAddress ip, uint16_t port, network_interface_t nif=0);
int connect(const char *host, uint16_t port, network_interface_t nif=0);
// EXAMPLE USAGE
TCPClient client;
byte server[] = { 74, 125, 224, 72 }; // Google
void setup()
{
// Make sure your Serial Terminal app is closed before powering your device
Serial.begin(9600);
// Wait for a USB serial connection for up to 30 seconds
waitFor(Serial.isConnected, 30000);
Serial.println("connecting...");
if (client.connect(server, 80))
{
Serial.println("connected");
client.println("GET /search?q=unicorn HTTP/1.0");
client.println("Host: www.google.com");
client.println("Content-Length: 0");
client.println();
}
else
{
Serial.println("connection failed");
}
}
void loop()
{
if (client.available())
{
char c = client.read();
Serial.print(c);
}
if (!client.connected())
{
Serial.println();
Serial.println("disconnecting.");
client.stop();
for(;;);
}
}
When using TCP with debugging logs enabled, you might see something like this:
0000182000 [wiring] ERROR: recv error = 113
These errors are documented in the POSIX error codes list. From code, you can find this underlying error code value in the global variable errno
or using getWriteError()
.
nif
is the network interface to use. This is typically omitted, in which case the primary network
inteface is used (cellular or Wi-Fi). You can, however pass Ethernet
, WiFi
, or Cellular
as this
parameter, which will only use that interface to make the outbound TCP connection.
In Device OS 6.2.0 and later, nif
can be Tether
to make connections to a device
such as a Raspberry Pi connected by UART serial.
Cellular Devices (B-Series SoM, Tracker SoM, Tracker One, Boron, E404X, E-Series, and Electron):
On cellular devices, be careful interacting with web hosts with TCPClient
or libraries using TCPClient
. These can use a lot of data in a short period of time. To keep the data usage low, use Particle.publish
along with webhooks.
Direct TCP, UDP, and DNS do not consume Data Operations from your monthly or yearly quota. However, they do use cellular data and could cause you to exceed the monthly data limit for your account.