Publish

Particle.publish - Publish

Since 6.2.0:

Particle.publish publishes an event from a device. This can be received by zero or more subscribers, including:

  • External services using a webhook
  • A Logic block to perform operations in the cloud
  • Another device using Particle.subscribe()
  • The server-sent events (SSE) data stream

There are a variety of overloads for this function, including:

// PROTOTYPES
particle::Future<bool> publish(const char* name, const char* data, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const String& data, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const char* data, size_t size, particle::ContentType type, PublishFlags flags = PublishFlags());
particle::Future<bool> publish(const char* name, const particle::EventData& data, PublishFlags flags = PublishFlags());

name - Particle.publish - Publish

This is the name of the event, which can be 1 - 64 ASCII characters.

data (string) - Particle.publish - Publish

The event data can consist of UTF-8 characters. The length depends on the device and Device OS version, but is typically limited to 1024 bytes.

This can be specified as a const char * (pointer to c-string, null-terminated), or a reference to a String object.

data (pointer and length) - Particle.publish - Publish

In Device OS 6.2 and later, the data can be specified with a pointer and length. This is typically used for binary data, and in particular, data that can contain a null byte. It can be used for text if your data source is not null-terminated.

data (EventData) - Particle.publish - Publish

The EventData overload does not require a ContentType value because it is used for structured data in a Variant and is always encoded as CBOR over-the-air, and JSON in webhooks and other locations. It can optionally include binary data.

contentType

Content Type Constant MIME Type
ContentType::TEXT text/plain; charset=utf-8
ContentType::JPEG image/jpeg
ContentType::PNG image/png
ContentType::BINARY application/octet-stream

The content type provides a hint to the receiver for what the data is. This includes the console, which can render some types of data in the event stream.

Future - Particle.publish - Publish

The return type of the Particle.publish function is particle::Future<bool>. There are three common ways to use this:

// EXAMPLE 1
Particle.publish("myEvent");

// EXAMPLE 2
bool bResult = Particle.publish("myEvent", eventData, WITH_ACK);

// EXAMPLE 3
Future<bool> futureResult = Particle.publish("myEvent");

In Example 1, you do not care about whether the call succeeds or not, and this will not wait for the data to be acknowledged by the cloud.

In Example 2, you can check bResult. If true, the publish was successfully made to the cloud. This will block until the packet is acknowledged by the cloud.

In Example 3, you use the future which decouples the waiting and the getting results. This can be useful if you are using a finite state machine. See Future for more information.