Device OS API

Introduction

Getting started

Using Particle primitives like Particle.publish is how you communicate between your Particle device, the Internet, and external services.

If you haven't programmed in C++ or Arduino recently and would like a refresher, see language syntax.

Navigation

You are viewing the single-page version of the Device OS API reference manual.

It is also available divided into small sections if you prefer that style. Small sections also work better on mobile devices and small tablets.

Cloud functions

Overview of API field limits

• Limits are in bytes of UTF-8 encoded characters.
• ²On Gen 2 devices (Photon, P1, Electron, E-Series), the limit is 864 characters,
• ³On the P2, Photon 2, and Gen 3 devices (Argon, Boron, B-Series SoM, Tracker SoM, and E404X) the limit is 1024 characters.
• The 0.8.0 - 2.x column includes all 2.x LTS versions. Higher limits will not be back-ported to 2.x LTS.

Instead of hardcoding these values, you should use these definitions:

• particle::protocol::MAX_VARIABLE_KEY_LENGTH
• particle::protocol::MAX_VARIABLE_VALUE_LENGTH
• particle::protocol::MAX_FUNCTION_KEY_LENGTH
• particle::protocol::MAX_FUNCTION_ARG_LENGTH
• particle::protocol::MAX_EVENT_NAME_LENGTH
• particle::protocol::MAX_EVENT_DATA_LENGTH

Additionally, some older Boron and B-Series SoM with a SARA-R410M-02B modem (LTE Cat M1) may have a limit of 782 bytes instead of 1024 bytes, see Particle.maxEventDataSize() for more information.

Particle.variable()

Expose a variable through the Cloud so that it can be called with GET /v1/devices/{DEVICE_ID}/{VARIABLE}. Returns a success value - true when the variable was registered.

Particle.variable registers a variable, so its value can be retrieved from the cloud in the future. You only call Particle.variable once per variable, and the variable is typically a global variable. You can change the value of the underlying global variable as often as you want; the value is only retrieved when requested, so simply changing the global variable does not use any data operations. Each request of the value from the cloud is one data operation. You do not call Particle.variable when you change the value.

The variable must be one of:

• A global variable
• A static local variable within a function
• A class member (with the class allocated as a global or using new, not stack allocated)
• A static class member (global, heap, or stack allocated)
• Heap allocated storage (new, malloc, etc.)

The underlying variable must not be a local variable allocated on the stack within a function, such as setup(), as the storage for it will go away after the function exits and the variable will not work properly.

// EXAMPLE USAGE

bool flag = false;
int analogvalue = 0;
double tempC = 0;
char *message = "my name is particle";
String aString;

void setup()
{
  Particle.variable("flag", flag);
  Particle.variable("analogvalue", analogvalue);
  Particle.variable("temp", tempC);
  if (Particle.variable("mess", message) == false)
  {
      // variable not registered!
  }
  Particle.variable("mess2", aString);

  pinMode(A0, INPUT);
}

void loop()
{
  // Read the analog value of the sensor (TMP36)
  analogvalue = analogRead(A0);
  // Convert the reading into degree Celsius
  tempC = (((analogvalue * 3.3) / 4095) - 0.5) * 100;
  delay(200);
}

Each variable retrieval uses one Data Operation from your monthly or yearly quota. Setting the variable does not use Data Operations.

Up to 20 cloud variables may be registered and each variable name is limited to a maximum of 12 characters (prior to 0.8.0), 64 characters (since 0.8.0).

Note: Only use letters, numbers, underscores and dashes in variable names. Spaces and special characters may be escaped by different tools and libraries causing unexpected results.

Variables can only be read using the Particle API, or tools that use the API, like the console, CLI, and mobile apps. It's not possible to directly read a variable from another device, even on the same account. Publish and subscribe can be used if you need device-to-device communication.

For non-product devices, only the account that has claimed the device can read variable values from it.

For product devices, if the device is claimed, the device owner's account can read variable values from it. Additionally, the product owner can read variable values whether the device is claimed or not.

When using the default AUTOMATIC system mode, the cloud variables must be registered in the setup() function. The information about registered variables will be sent to the cloud when the setup() function has finished its execution. In the SEMI_AUTOMATIC and MANUAL system modes, the variables must be registered before Particle.connect() is called.

Before 1.5.0: Variable and function registrations are only sent up once, about 30 seconds after connecting to the cloud. When using the AUTOMATIC system mode, make sure you register your cloud variables as early as possible in the setup() function, before you do any lengthy operations, delays, or things like waiting for a key press. Calling Particle.variable() after the registration information has been sent does not re-send the request and the variable will not work.

String data has a maximum size of 255 to 1024 bytes of UTF-8 characters; see API Field Limits as the limit varies depending on Device OS version and sometimes the device. String variables must be UTF-8 encoded. You cannot send arbitrary binary data or other character sets like ISO-8859-1. If you need to send binary data you can use a text-based encoding like Base64.

Prior to 0.4.7 firmware, variables were defined with an additional 3rd parameter to specify the data type of the variable. From 0.4.7 onward, the system can infer the type from the actual variable. Additionally, the variable address was passed via the address-of operator (&). With 0.4.7 and newer, this is no longer required.

// EXAMPLE USAGE - pre-0.4.7 syntax

bool flag = false;
int analogvalue = 0;
double tempC = 0;
char *message = "my name is particle";

void setup()
{
  Particle.variable("flag", &flag, BOOLEAN);
  Particle.variable("analogvalue", &analogvalue, INT);
  Particle.variable("temp", &tempC, DOUBLE);
  if (Particle.variable("mess", message, STRING) == false)
  {
      // variable not registered!
  }
  pinMode(A0, INPUT);
}

There are four supported data types:

• BOOLEAN
• INT
• DOUBLE
• STRING (UTF-8 encoded characters)

# EXAMPLE REQUEST IN TERMINAL
# Device ID is 0123456789abcdef
# Your access token is f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0
curl "https://api.particle.io/v1/devices/0123456789abcdef/flag" -H "Authorization: Bearer f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0"
curl "https://api.particle.io/v1/devices/0123456789abcdef/analogvalue" -H "Authorization: Bearer f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0"
curl "https://api.particle.io/v1/devices/0123456789abcdef/temp" -H "Authorization: Bearer f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0"
curl "https://api.particle.io/v1/devices/0123456789abcdef/mess" -H "Authorization: Bearer f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0"

# In return you'll get something like this:
false
960
27.44322344322344
my name is particle

Particle.variable() - calculated

Since 1.5.0: It is also possible to register a function to compute a cloud variable. This can be more efficient if the computation of a variable takes a lot of CPU or other resources. It can also be an alternative to using a Particle.function(). A function is limited to a single int (32-bit) return value, but you can return bool, double, int, String from a Particle.variable. String data has a maximum size of 255 to 1024 bytes of UTF-8 characters; see API Field Limits as the limit varies depending on Device OS version and sometimes the device.

Such a function should return a value of one of the supported variable types and take no arguments. The function will be called only when the value of the variable is requested.

The callback function is called application loop thread context, between calls to loop(), during Particle.process(), and delay().

// EXAMPLE USAGE - registering functions as cloud variables

bool flag() {
  return false;
}

int analogvalue() {
  // Read the analog value of the sensor (TMP36)
  return analogRead(A0);
}

double tempC() {
  // Convert the reading into degree Celsius
  return (((analogvalue() * 3.3) / 4095) - 0.5) * 100;
}

String message() {
  return "my name is particle";
}

void setup()
{
  Particle.variable("flag", flag);
  Particle.variable("analogvalue", analogvalue);
  Particle.variable("temp", tempC);
  Particle.variable("mess", message);

  pinMode(A0, INPUT);
}

void loop()
{
}

It is also possible to pass a std::function, allowing the calculation function to be a method of a class:

// CALCULATED FUNCTION IN CLASS EXAMPLE
class MyClass {
public:
    MyClass();
    virtual ~MyClass();

    void setup();

    String calculateCounter();

protected:
    int counter = 0;
};

MyClass::MyClass() {

}

MyClass::~MyClass() {

}

void MyClass::setup() {
    Particle.variable("counter", [this](){ return this->calculateCounter(); });
}

String MyClass::calculateCounter() {
    return String::format("counter retrieved %d times", ++counter);
}

MyClass myClass;

void setup() {
    myClass.setup();
}

void loop() {
}

Each variable retrieval uses one Data Operation from your monthly or yearly quota. Setting the variable does not use Data Operations.

Particle.function()

Expose a function through the Cloud so that it can be called with POST /v1/devices/{DEVICE_ID}/{FUNCTION}.

Particle.function allows code on the device to be run when requested from the cloud API. You typically do this when you want to control something on your device, say a LCD display or a buzzer, or control features in your firmware from the cloud.

// SYNTAX
bool success = Particle.function("funcKey", funcName);

// Cloud functions must return int and take one String
int funcName(String extra) {
  return 0;
}

Each function call request and response uses one Data Operation from your monthly or yearly quota. Setting up function calls does not use Data Operations.

Up to 15 cloud functions may be registered and each function name is limited to a maximum of 12 characters (prior to 0.8.0), 64 characters (since 0.8.0).

Note: Only use letters, numbers, underscores and dashes in function names. Spaces and special characters may be escaped by different tools and libraries causing unexpected results. A function callback procedure needs to return as quickly as possible otherwise the cloud call will timeout.

The callback function is called application loop thread context, between calls to loop(), during Particle.process(), and delay().

In order to register a cloud function, the user provides the funcKey, which is the string name used to make a POST request and a funcName, which is the actual name of the function that gets called in your app. The cloud function has to return an integer; -1 is commonly used for a failed function call.

A cloud function is set up to take one argument of the String datatype. The argument has a maximum size of 64 to 1024 bytes of UTF-8 characters; see API Field Limits as the limit varies depending on Device OS version and sometimes the device.

Functions can only be triggered using the Particle API, or tools that use the API, like the console, CLI, and mobile apps. It's not possible to directly call a function from another device, even on the same account. Publish and subscribe can be used if you need device-to-device communication.

For non-product devices, only the account that has claimed the device can call a function on it.

For product devices, if the device is claimed, the device owner's account can call a function on it. Additionally, the product owner can call a function whether the device is claimed or not.

When using the default AUTOMATIC system mode, the cloud functions must be registered in the setup() function. The information about registered functions will be sent to the cloud when the setup() function has finished its execution. In the SEMI_AUTOMATIC and MANUAL system modes, the functions must be registered before Particle.connect() is called.

Before 1.5.0: Variable and function registrations are only sent up once, about 30 seconds after connecting to the cloud. When using the AUTOMATIC system mode, make sure you register your cloud functions as early as possible in the setup() function, before you do any lengthy operations, delays, or things like waiting for a key press. Calling Particle.function() after the registration information has been sent does not re-send the request and the function will not work.

// EXAMPLE USAGE

int brewCoffee(String command);

void setup()
{
  // register the cloud function
  Particle.function("brew", brewCoffee);
}

void loop()
{
  // this loops forever
}

// this function automagically gets called upon a matching POST request
int brewCoffee(String command)
{
  // look for the matching argument "coffee" <-- max of 64 characters long
  if(command == "coffee")
  {
    // some example functions you might have
    //activateWaterHeater();
    //activateWaterPump();
    return 1;
  }
  else return -1;
}

You can expose a method on a C++ object to the Cloud.

// EXAMPLE USAGE WITH C++ OBJECT

class CoffeeMaker {
  public:
    CoffeeMaker() {
    }

    void setup() {
      // You should not call Particle.function from the constructor 
      // of an object that will be declared as a global variable.
      Particle.function("brew", &CoffeeMaker::brew, this);
    }

    int brew(String command) {
      // do stuff
      return 1;
    }
};

CoffeeMaker myCoffeeMaker;

void setup() {
    myCoffeeMaker.setup();
}

The API request will be routed to the device and will run your brew function. The response will have a return_value key containing the integer returned by brew.

COMPLEMENTARY API CALL
POST /v1/devices/{DEVICE_ID}/{FUNCTION}

# EXAMPLE REQUEST
curl https://api.particle.io/v1/devices/0123456789abcdef/brew \
     -H "Authorization: Bearer f8a4d380cb6ffffffffffffffffffaf5e496ddf0c0" \
     -d "args=coffee"

Replace the access token with a valid access token, such as from particle token create.

Particle.publish()

Publish an event through the Particle Device Cloud. This can trigger a webhook to an external service, a Logic block to perform operations in the cloud, or another device using Particle.subscribe().

See Publish, below.

Particle.subscribe()

Subscribe to events published by devices.

See Subscribe, below.

Particle.unsubscribe()

Removes all subscription handlers previously registered with Particle.subscribe().

// SYNTAX
Particle.unsubscribe();

There is no function to unsubscribe a single event handler.

Particle.ledger

Since 6.1.0:

Request a ledger from the cloud. Returns a Ledger object to read or write the data in the ledger.

This operation is asynchronous and the data will not be available until synchronized with the cloud. You will typically call this from setup() and you can do so before connected to the cloud.

The type of ledger (device-to-cloud or cloud-to-device), as well as the ledger scope (organization, product, or device) is determined when the ledger is created on the cloud side, so it is not specified when you request the ledger. You must first create a ledger definition in the cloud; you cannot create a new ledger definition using the device-side API.

The first time a device comes online specifying a device to cloud ledger, a new ledger instance will be created for the device, however.

Ledger names consist only of lowercase alphanumeric and dash, up to 32 characters, and are unique across all scopes.

// PROTOTYPE
Ledger ledger(const char* name);

// EXAMPLE
Ledger sensors;

void setup() {
    sensors = Particle.ledger("sensors");
}

Particle.maxEventDataSize()

Since 3.1.0:

// PROTOTYPE
int maxEventDataSize();

// SYNTAX
Log.info("eventDataSize=%d", Particle.maxEventDataSize());

Returns the maximum size of the data payload for events. This is normally specified per platform, however Boron and B-Series SoM with a SARA-R410M-02B that have an older version of the modem firmware (02.03 and earlier), the limit is 782 instead of 1024 bytes due to modem firmware limitations.

This value is only available when connected to the cloud. At other times, SYSTEM_ERROR_INVALID_STATE (-210) is returned.

Particle.maxVariableValueSize()

Since 3.1.0:

// PROTOTYPE
int maxVariableValueSize();

// SYNTAX
Log.info("maxVariableValueSize=%d", Particle.maxVariableValueSize());

Returns the maximum size of the string variable data.

Returns the maximum size of the data payload for events. This is normally specified per platform, however Boron and B-Series SoM with a SARA-R410M-02B that have an older version of the modem firmware (02.03 and earlier), the limit is 782 instead of 1024 bytes due to modem firmware limitations.

This value is only available when connected to the cloud. At other times, SYSTEM_ERROR_INVALID_STATE (-210) is returned.

Particle.maxFunctionArgumentSize()

Since 3.1.0:

// PROTOTYPE
int maxFunctionArgumentSize();

// SYNTAX
Log.info("maxFunctionArgumentSize=%d", Particle.maxFunctionArgumentSize());

Returns the maximum size of the function argument data.

Returns the maximum size of the data payload for events. This is normally specified per platform, however Boron and B-Series SoM with a SARA-R410M-02B that have an older version of the modem firmware (02.03 and earlier), the limit is 782 instead of 1024 bytes due to modem firmware limitations.

This value is only available when connected to the cloud. At other times, SYSTEM_ERROR_INVALID_STATE (-210) is returned.

Particle.publishVitals()

Since 1.2.0:

// SYNTAX

system_error_t Particle.publishVitals(system_tick_t period_s = particle::NOW)

Particle.publishVitals();  // Publish vitals immediately
Particle.publishVitals(particle::NOW);  // Publish vitals immediately
Particle.publishVitals(5);  // Publish vitals every 5 seconds, indefinitely
Particle.publishVitals(0);  // Publish immediately and cancel periodic publishing

Publish vitals information

Provides a mechanism to control the interval at which system diagnostic messages are sent to the cloud. Subsequently, this controls the granularity of detail on the fleet health metrics.

Argument(s):

• period_s The period (in seconds) at which vitals messages are to be sent to the cloud (default value: particle::NOW)

  • particle::NOW - A special value used to send vitals immediately
  • 0 - Publish a final message and disable periodic publishing
  • s - Publish an initial message and subsequent messages every s seconds thereafter

Returns:

A system_error_t result code

• system_error_t::SYSTEM_ERROR_NONE
• system_error_t::SYSTEM_ERROR_IO

Examples:

// EXAMPLE - Publish vitals intermittently

bool condition;

setup () {
}

loop () {
  ...  // Some logic that either will or will not set "condition"

  if ( condition ) {
    Particle.publishVitals();  // Publish vitals immmediately
  }
}

// EXAMPLE - Publish vitals periodically, indefinitely

setup () {
  Particle.publishVitals(3600);  // Publish vitals each hour
}

loop () {
}

// EXAMPLE - Publish vitals each minute and cancel vitals after one hour

size_t start = millis();

setup () {
  Particle.publishVitals(60);  // Publish vitals each minute
}

loop () {
  // Cancel vitals after one hour
  if (3600000 < (millis() - start)) {
    Particle.publishVitals(0);  // Publish immediately and cancel periodic publishing
  }
}

Since 1.5.0:

You can also specify a value using chrono literals, for example: Particle.publishVitals(1h) for 1 hour.

Sending device vitals does not consume Data Operations from your monthly or yearly quota. However, for cellular devices they do use cellular data, so unnecessary vitals transmission can lead to increased data usage, which could result in hitting the monthly data limit for your account.

NOTE: Diagnostic messages can be viewed in the Console. Select the device in question, and view the messages under the "EVENTS" tab.

Device vitals are sent:

• On handshake (at most every three days, but can be more frequent if waking from some sleep modes)
• Before an OTA firmware flash if last vitals were sent more than 5 minutes ago
• Under user control from device firmware when using Particle.publishVitals()
• From the cloud side (API or console) when requested

The actual device vitals are communicated to the cloud in a concise binary CoAP payload. The large JSON event you see in the event stream is a synthetic event. It looks like it's coming from the device but that format is not transmitted over the network connection.

It is not possible to disable the device vitals messages, however they do not count as a data operation.

Particle.connect()

Particle.connect() connects the device to the Cloud. This will automatically activate the network connection and attempt to connect to the Particle cloud if the device is not already connected to the cloud.

void setup() {}

void loop() {
  if (Particle.connected() == false) {
    Particle.connect();
  }
}

After you call Particle.connect(), your loop will not be called again until the device finishes connecting to the Cloud. Typically, you can expect a delay of approximately one second.

In most cases, you do not need to call Particle.connect(); it is called automatically when the device turns on. Typically you only need to call Particle.connect() after disconnecting with Particle.disconnect() or when you change the system mode.

Connecting to the cloud does not use Data Operation from your monthly or yearly quota. However, for cellular devices it does use cellular data, so unnecessary connection and disconnection can lead to increased data usage, which could result in hitting the monthly data limit for your account.

On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker), prior to Device OS 2.0.0, you needed to call WiFi.on() or Cellular.on() before calling Particle.connect(). This is not necessary on Gen 2 devices (any Device OS version) or with 2.0.0 and later.

Particle.connectionInterface()

Since 5.6.0:

Returns the current interface used for the Particle cloud connection in Device OS 5.6.0 and later.

// PROTOTYPE
spark::NetworkClass& connectionInterface();

// EXAMPLE
if (Particle.connectionInterface() == WiFi) {
    // WiFi
} else if (Particle.connectionInterface() == Cellular) {
    // Cellular
} else if (Particle.connectionInterface() == Network) {
    // Generic
}

Particle.disconnect()

Particle.disconnect() disconnects the device from the Cloud.

SerialLogHandler logHandler;
int counter = 10000;

void doConnectedWork() {
  digitalWrite(D7, HIGH);
  Log.info("Working online");
}

void doOfflineWork() {
  digitalWrite(D7, LOW);
  Log.info("Working offline");
}

bool needConnection() {
  --counter;
  if (0 == counter)
    counter = 10000;
  return (2000 > counter);
}

void setup() {
  pinMode(D7, OUTPUT);
}

void loop() {
  if (needConnection()) {
    if (!Particle.connected())
      Particle.connect();
    doConnectedWork();
  } else {
    if (Particle.connected())
      Particle.disconnect();
    doOfflineWork();
  }
}

Since 2.0.0:

When disconnecting from the Cloud, by default, the system does not wait for any pending messages, such as cloud events, to be actually sent to acknowledged by the Cloud. This behavior can be changed either globally via Particle.setDisconnectOptions() or by passing an options object to Particle.disconnect(). The timeout parameter controls how long the system can wait for the pending messages to be acknowledged by the Cloud.

// EXAMPLE - disconnecting from the Cloud gracefully
Particle.disconnect(CloudDisconnectOptions().graceful(true).timeout(5000));

// EXAMPLE - using chrono literals to specify a timeout
Particle.disconnect(CloudDisconnectOptions().graceful(true).timeout(5s));

Note that the actual disconnection happens asynchronously. If necessary, waitUntil(Particle.disconnected) can be used to wait until the device has disconnected from the Cloud.

While this function will disconnect from the Cloud, it will keep the connection to the network. If you would like to completely deactivate the network module, use WiFi.off() or Cellular.off() as appropriate.

*NOTE: When the device is disconnected, many features are not possible, including over-the-air updates, reading Particle.variables, and calling Particle.functions.

If you disconnect from the Cloud, you will NOT BE ABLE to flash new firmware over the air. Safe mode can be used to reconnect to the cloud.

Since 5.6.0:

Automatic connection management occurs on the next connection following a disconnection from the Particle cloud. This happens automatically if the underlying network (cellular, Wi-Fi, or ethernet) becomes unavailable.

In some special cases you can manually disconnect to force automatic connection management. You should avoid doing this frequently as the device will not have cloud connectivity during the disconnection, discovery, and reconnection process. It will also use cellular data (but not data operations).

// EXAMPLE
Particle.disconnect();
waitFor(Particle.disconnected, 10000);
Particle.connect();

Clear session

When your device connects to the Particle cloud, if often can do so by resuming the previous session. This dramatically reduces the amount of data used, from around 5-6 Kbytes of data for a full handshake to hundreds of bytes of data for a resume. While a full session handshake does not use data operations, if done excessively it can impact the total data usage on cellular devices. Sessions are automatically renegotiated every 3 days for security reasons.

Under normal circumstances you will never have to manually invalidate the current session. However, if you have a need to do so, this is the best way:

auto opts = CloudDisconnectOptions().clearSession(true);
Particle.disconnect(opts);

You may see references to spark/device/session/end in the community forums, however that method should not be used and may be deprecated in the future. The clearSession flag should be used instead.

Particle.connected()

Returns true when connected to the Cloud, and false when disconnected from the Cloud.

// SYNTAX
Particle.connected();


// EXAMPLE USAGE
SerialLogHandler logHandler;

void setup() {
}

void loop() {
  if (Particle.connected()) {
    Log.info("Connected!");
  }
  delay(1000);
}

This call is fast and can be called frequently without performance degradation.

Particle.disconnected()

Returns true when disconnected from the Cloud, and false when connected to Cloud.

Particle.setDisconnectOptions()

Since 2.0.0:

// EXAMPLE
Particle.setDisconnectOptions(CloudDisconnectOptions().graceful(true).timeout(5000));

// EXAMPLE
Particle.setDisconnectOptions(CloudDisconnectOptions().graceful(true).timeout(5s));

Sets the options for when disconnecting from the cloud, such as from Particle.disconnect(). The default is to abruptly disconnect, however, you can use graceful disconnect mode to make sure pending events have been sent and the cloud notified that a disconnect is about to occur. Since this could take some time if there is poor cellular connectivity, a timeout can also be provided in milliseconds or using chrono literals. This setting will be used for future disconnects until the system is reset.

Note: This method sets the disconnection options globally, meaning that any method that causes the device to disconnect from the Cloud, such as System.reset(), will do so gracefully.

Particle.keepAlive()

On all Gen 3 devices (Argon, Boron, B-Series SoM, Tracker) and Gen 2 cellular devices:

Sets the duration between keep-alive messages used to maintain the connection to the cloud.

// SYNTAX
Particle.keepAlive(23 * 60);    // send a ping every 23 minutes

A keep-alive is used to implement "UDP hole punching" which helps maintain the connection from the cloud to the device. A temporary port-forwarded back-channel is set up by the network to allow packets to be sent from the cloud to the device. As this is a finite resource, unused back-channels are periodically deleted by the network.

Should a device becomes unreachable from the cloud (such as a timed out function call or variable get), one possible cause of this is that the keep alives have not been sent often enough.

The keep-alive for cellular devices duration varies by mobile network operator. The default keep-alive is set to 23 minutes, which is sufficient to maintain the connection on Particle SIM cards. 3rd party SIM cards will need to determine the appropriate keep alive value, typically ranging from 30 seconds to several minutes.

Note: Each keep alive ping consumes 122 bytes of data (61 bytes sent, 61 bytes received).

For Ethernet, you will probably want to set a keepAlive to 25 seconds, like the Argon. In some cases, it could be raised to 2 to 5 minutes; this is dependent on how quickly the Internet router at the site releases port-forwarded back-channel.

For the Argon, the keep-alive is not generally needed. However, in unusual networking situations if the network router/firewall removes the port forwarded back-channels unusually aggressively, you may need to use a keep-alive.

Keep-alives do not use Data Operations from your monthly or yearly quota. However, for cellular devices they do use cellular data, so setting it to a very small value can cause increased data usage, which could result in hitting the monthly data limit for your account.

Since 1.5.0:

You can also specify a value using chrono literals, for example: Particle.keepAlive(2min) for 2 minutes.

Particle.process()

• Using SYSTEM_THREAD(ENABLED) is recommended for most applications. When using threading mode you generally do not need to use Particle.process(). With Device OS 6.2.0 and later, system thread is always enabled. For additional information, see non-threaded system mode.

• If you are using SYSTEM_MODE(AUTOMATIC) (the default if you do not specify), or SEMI_AUTOMATIC you generally do not need to Particle.process() unless your code blocks and prevents loop from returning and does not use delay() in any inner blocking loop. In other words, if you block loop() from returning you must call either delay() or Particle.process() within your blocking inner loop.

• If you are using SYSTEM_MODE(MANUAL) you must call Particle.process() frequently, preferably on any call to loop() as well as any locations where you are blocking within loop().

Particle.process() checks for the incoming messages from the Cloud, and processes any messages that have come in. It also sends keep-alive pings to the Cloud, so if it's not called frequently, the connection to the Cloud may be lost.

It will also update the ApplicationWatchdog timer using ApplicationWatchdog::checkin().

Particle.syncTime()

Synchronize the time with the Particle Device Cloud. This happens automatically when the device connects to the Cloud. However, if your device runs continuously for a long time, you may want to synchronize once per day or so.

#define ONE_DAY_MILLIS (24 * 60 * 60 * 1000)
unsigned long lastSync = millis();

void loop() {
  if (millis() - lastSync > ONE_DAY_MILLIS) {
    // Request time synchronization from the Particle Device Cloud
    Particle.syncTime();
    lastSync = millis();
  }
}

Note that this function sends a request message to the Cloud and then returns. The time on the device will not be synchronized until some milliseconds later when the Cloud responds with the current time between calls to your loop. See Particle.syncTimeDone(), Particle.timeSyncedLast(), Time.isValid() and Particle.syncTimePending() for information on how to wait for request to be finished.

Synchronizing time does not consume Data Operations from your monthly or yearly quota. However, for cellular devices they do use cellular data, so unnecessary time synchronization can lead to increased data usage, which could result in hitting the monthly data limit for your account.

For more information about real-time clocks on Particle devices, see Learn more about real-time clocks.

Particle.syncTimeDone()

Since 0.6.1:

Returns true if there is no syncTime() request currently pending or there is no active connection to Particle Device Cloud. Returns false when there is a pending syncTime() request.

// SYNTAX
Particle.syncTimeDone();


// EXAMPLE
SerialLogHandler logHandler;

void loop()
{
  // Request time synchronization from the Particle Device Cloud
  Particle.syncTime();
  // Wait until the device receives time from Particle Device Cloud (or connection to Particle Device Cloud is lost)
  waitUntil(Particle.syncTimeDone);
  // Print current time
  Log.info("Current time: %s", Time.timeStr().c_str());
}

See also Particle.timeSyncedLast() and Time.isValid().

Particle.syncTimePending()

Since 0.6.1:

Returns true if there a syncTime() request currently pending. Returns false when there is no syncTime() request pending or there is no active connection to Particle Device Cloud.

// SYNTAX
Particle.syncTimePending();


// EXAMPLE
SerialLogHandler logHandler;

void loop()
{
  // Request time synchronization from the Particle Device Cloud
  Particle.syncTime();
  // Wait until the device receives time from Particle Device Cloud (or connection to Particle Device Cloud is lost)
  while(Particle.syncTimePending())
  {
    //
    // Do something else
    //

    Particle.process();
  }
  // Print current time
  Log.info("Current time: %s", Time.timeStr().c_str());
}

See also Particle.timeSyncedLast() and Time.isValid().

Particle.timeSyncedLast()

// EXAMPLE

SerialLogHandler logHandler;

#define ONE_DAY_MILLIS (24 * 60 * 60 * 1000)

void loop() {
  time_t lastSyncTimestamp;
  unsigned long lastSync = Particle.timeSyncedLast(lastSyncTimestamp);
  if (millis() - lastSync > ONE_DAY_MILLIS) {
    unsigned long cur = millis();
    Log.info("Time was last synchronized %lu milliseconds ago", millis() - lastSync);
    if (lastSyncTimestamp > 0)
    {
      Log.info("Time received from Particle Device Cloud was: ", Time.timeStr(lastSyncTimestamp).c_str());
    }
    // Request time synchronization from Particle Device Cloud
    Particle.syncTime();
    // Wait until the device receives time from Particle Device Cloud (or connection to Particle Device Cloud is lost)
    waitUntil(Particle.syncTimeDone);
    // Check if synchronized successfully
    if (Particle.timeSyncedLast() >= cur)
    {
      // Print current time
      Log.info("Current time: %s", Time.timeStr().c_str());
    }
  }
}

Since 0.6.1:

Used to check when time was last synchronized with Particle Device Cloud.

// SYNTAX
Particle.timeSyncedLast();
Particle.timeSyncedLast(timestamp);

Returns the number of milliseconds since the device began running the current program when last time synchronization with Particle Device Cloud was performed.

This function takes one optional argument:

• timestamp: time_t variable that will contain a UNIX timestamp received from Particle Device Cloud during last time synchronization

It is possible that the call will block for an indeterminate amount of time, possibly for as long as 10 minutes. This can occur if the system thread is busy trying to reconnect to cellular and is unable to do so. Doing operations that access the cellular modem or require access to the system thread (as is the case for Particle.timeSyncedLast()) from a separate worker thread is a good workaround.

Get public IP

Using this feature, the device can programmatically know its own public IP address.

SYSTEM_THREAD(ENABLED);

SerialLogHandler logHandler;
bool nameRequested = false;

// Open a serial terminal and see the IP address printed out
void subscriptionHandler(const char *topic, const char *data)
{
    Log.info("topic=%s data=%s", topic, data);
}

void setup()
{
    Particle.subscribe("particle/device/ip", subscriptionHandler);
}

void loop() {
    if (Particle.connected() && !nameRequested) {
        nameRequested = true;
        Particle.publish("particle/device/ip");
    }
}

Note: Calling Particle

Get device name

This gives you the device name that is stored in the cloud.

SYSTEM_THREAD(ENABLED);

SerialLogHandler logHandler;
bool nameRequested = false;

// Open a serial terminal and see the IP address printed out
void subscriptionHandler(const char *topic, const char *data)
{
    Log.info("topic=%s data=%s", topic, data);
}

void setup()
{
    Particle.subscribe("particle/device/name", subscriptionHandler);
}

void loop() {
    if (Particle.connected() && !nameRequested) {
        nameRequested = true;
        Particle.publish("particle/device/name");
    }
}

Instead of fetching the name from the cloud each time, you can fetch it and store it in retained memory or EEPROM. The DeviceNameHelperRK library makes this easy. The link includes instructions and the library is available in Particle Workbench by using Particle: Install Library or in the Web IDE by searching for DeviceNameHelperRK.

Get random seed

Grab 40 bytes of randomness from the cloud and {e}n{c}r{y}p{t} away!

LogHandler logHandler;

void handler(const char *topic, const char *data) {
    Log.info("topic=%s data=%s", topic, data);
}

void setup() {
    Serial.begin(115200);
    Particle.subscribe("particle/device/random", handler);
    Particle.publish("particle/device/random");
}

Publish

Publish an event through the Particle Device Cloud. This can trigger a webhook to an external service, a Logic block to perform operations in the cloud, or another device using Particle.subscribe().

This feature allows the device to generate an event based on a condition. For example, you could connect a motion sensor to the device and have the device generate an event whenever motion is detected.

Limits - Publish

Each event contains:

• An event name (1-64 ASCII characters)
• Event data (optional)
• A timestamp (generated in the cloud)
• Device ID (identifies the publisher of the event)

The size and contents of the event data vary depending on the version of Device OS running on the device.

Typed publish - Publish

Since 6.2.0:

In Device OS 6.2 and later, typed publish is supported. This allows the Content-Type of the publish data to be specified, and allows for binary data payloads. The following types are supported:

Additionally, JSON (text/json) structured data is supported. This is encoded using an EventData object, which is a Variant. The Variant can be created from a JSON text string, or built programmatically by adding fields.

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

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.

Particle.publish (classic API) - Publish

Particle.publish pushes the value out of the device at a time controlled by the device firmware. Particle.variable allows the value to be pulled from the device when requested from the cloud side.

Cloud events have the following properties:

• name (1–64 ASCII characters)

Note: Only use letters, numbers, underscores, dashes and slashes in event names. Spaces and special characters may be escaped by different tools and libraries causing unexpected results.

• optional data. The data has a maximum size of 255 to 1024 bytes of UTF-8 characters; see API Field Limits as the limit varies depending on Device OS version and sometimes the device.

A device may not publish events beginning with a case-insensitive match for "spark". Such events are reserved for officially curated data originating from the Cloud.

Calling Particle.publish() when the cloud connection has been turned off will not publish an event. This is indicated by the return success code of false.

If the cloud connection is turned on and trying to connect to the cloud unsuccessfully, Particle.publish() may block for up to 20 seconds (normal conditions) to 10 minutes (unusual conditions). Checking Particle.connected() can before calling Particle.publish() can help prevent this.

String variables must be UTF-8 encoded. You cannot send arbitrary binary data or other character sets like ISO-8859-1. If you need to send binary data you can use a text-based encoding like Base64.

NOTE 1: Currently, a device can publish at rate of about 1 event/sec, with bursts of up to 4 allowed in 1 second. Back to back burst of 4 messages will take 4 seconds to recover.

NOTE 2: Particle.publish() and the Particle.subscribe() handler(s) share the same buffer. As such, calling Particle.publish() within a Particle.subscribe() handler will overwrite the subscribe buffer, corrupting the data! In these cases, copying the subscribe buffer's content to a separate char buffer prior to calling Particle.publish() is recommended.

NOTE 3: Public events are not supported by the cloud as of August 2020. Specifying PUBLIC or leaving out the publish scope essentially results in a private event.

For non-product devices, events published by a device can be subscribed to:

• By other devices claimed to the same account
• By webhooks for the user the device is claimed to
• By the SSE event stream for the user the device is claimed to

For product devices, events published by a device can be subscribed to:

• By other devices claimed to the same account, if the device is claimed
• By webhooks for the user the device is claimed to, if the device is claimed
• By the SSE event stream for the user the device is claimed to, if the device is claimed
• By product webhooks for the product the device is associated with, whether or not the device is claimed
• By the SSE event stream for the product the device is associated with, whether or not the device is claimed

Public events could previously be received by anyone on the Internet, and anyone could generate events to send to your devices. This did not turn out to a common use-case, and the ease at which you could accidentally use this mode, creating a security hole, caused it to be removed.

Each publish uses one Data Operation from your monthly or yearly quota. This is true for both WITH_ACK and NO_ACK modes.

• Publishes are not end-to-end confirmed. Even if the Particle.publish returns true, there is no guarantee that any recipient (another device, webhook, or SSE) will receive it.
• It is possible to receive an event more than once. The most common reason is a lost ACK, which will cause the device to send the event again. Storing a unique identifier in the event payload may help code defensively for this possibility.
• It is possible that events will arrive out-of-order. The most common cause is retransmission, but it can also occur because events can flow through different redundant servers, each with slightly difference latency, so it's possible that two event sent rapidly will arrive out-of-order as well. This is common for multi-part webhook responses.
• It is possible that even if Particle.publish returns false, the event will still be received by the cloud later. This occurs because the 20-second timeout is reached, so false is returned, but the event is still buffered in Device OS and will be retransmitted if the reconnection to the cloud succeeds.

Publish an event with the given name and no data.

// SYNTAX
Particle.publish(const char *eventName, PublishFlags flags);
Particle.publish(String eventName, PublishFlags flags);

Returns: A bool indicating success: (true or false)

// EXAMPLE USAGE
bool success;
success = Particle.publish("motion-detected");
if (!success) {
  // get here if event publish did not work
}

// EXAMPLE USAGE - This format is no longer necessary
// PRIVATE is the default and only option now
bool success;
success = Particle.publish("motion-detected", PRIVATE);
if (!success) {
  // get here if event publish did not work
}

// PROTOTYPES
particle::Future<bool> publish(const char* name);
particle::Future<bool> publish(const char* name, const char* data);

// EXAMPLE USAGE 1
Particle.publish("temperature", "19");

// EXAMPLE USAGE 2
int temp = 19;
Particle.publish("temperature", String(temp));

// EXAMPLE USAGE 3
float temp = 19.5;
Particle.publish("temperature", String::format("%.1f", temp);

Publish an event with the given name and data.

The data must be a string in the ASCII or UTF-8 character set. If you have an integer or floating point value, you'll need to convert it to a string first.

You cannot publish binary data with Particle.publish. To send binary data, convert it to a string using hex or Base 64 encoding.

While Base85 (Ascii85) provides a more dense encoding than Base64, it is not recommended if you are publishing data to be sent to an external server by a webhook. The Base85 alphabet includes the left curly bracket, and the {{ sequence is recognized as a mustache template delimiter during webhook processing, causing the data to be corrupted. The backslash can also cause unexpected data transformation.

// EXAMPLE - Check if event was queued for publishing successfully
float temp = 19.5;
bool success = Particle.publish("temperature", String::format("%.1f", temp);

// EXAMPLE - Check if event was queued for publishing successfully
float temp = 19.5;
bool success = Particle.publish("temperature", String::format("%.1f", temp);

Normally, you store or test the result of Particle.publish in a bool variable that indicates that the event was queued for publishing successfully, or reached the cloud, when used with WITH_ACK.

But what is the particle::Future<bool> in the prototype above? See the application note AN009 Firmware Examples for how to use a Future to make the otherwise synchronous Particle.publish() call asynchronous.

COMPLEMENTARY API CALL
GET /v1/events/{EVENT_NAME}

# EXAMPLE REQUEST
curl -H "Authorization: Bearer {ACCESS_TOKEN_GOES_HERE}" \
    https://api.particle.io/v1/events/motion-detected

# Will return a stream that echoes text when your event is published
event: motion-detected
data: {"data":"23:23:44","ttl":"60","published_at":"2014-05-28T19:20:34.638Z","deviceid":"0123456789abcdef"}

Cellular Devices (B-Series SoM, Tracker SoM, Tracker One, Boron, E404X, E-Series, and Electron):

// PROTOTYPES
particle::Future<bool> publish(const char* name, PublishFlags flags1, PublishFlags flags2 = PublishFlags());
particle::Future<bool> publish(const char* name, const char* data, PublishFlags flags1, PublishFlags flags2 = PublishFlags());

// SYNTAX

float temperature = sensor.readTemperature();  // by way of example, not part of the API
Particle.publish("t", String::format("%.2f",temperature), NO_ACK);  // make sure to convert to const char * or String

// SYNTAX
bool success = Particle.publish("motion-detected", NULL, WITH_ACK);

// No longer necessary, PRIVATE is always used even when not specified
bool success = Particle.publish("motion-detected", NULL, PRIVATE, WITH_ACK);

WITH_ACK flag

Since 0.6.1:

This flag causes Particle.publish() to return only after receiving an acknowledgement that the published event has been received by the Cloud.

If you do not use WITH_ACK then the request is still acknowledged internally, and retransmission attempted up to 3 times, but Particle.publish() will return more quickly.

Since 0.7.0:

// EXAMPLE - combining Particle.publish() flags
// No longer necessary, PRIVATE is always used even when not specified
Particle.publish("motion-detected", PRIVATE | WITH_ACK);

Particle.publish() flags can be combined using a regular syntax with OR operator (|).

For products, it's possible receive product events sent by devices using webhooks or the Server-Sent-Events (SSE) data stream.

// SYNTAX - DEPRECATED
Particle.publish(const char *eventName, const char *data, int ttl, PublishFlags flags);
Particle.publish(String eventName, String data, int ttl, PublishFlags flags);

Previously, there were overloads with a ttl (time-to-live) value. These have been deprecated as the ttl has never been supported by the Particle cloud. All events expire immediately if not subscribed to or exported from the Particle cloud using a webhook, integration like Google cloud, or the server-sent-events (SSE) stream.

Even if you use NO_ACK mode and do not check the result code from Particle.publish() it is possible that the call will still block for an indeterminate amount of time, possibly for as long as 10 minutes. This can occur if you publish while in the process of attempting to reconnect to the network. At a minimum, you should make sure that Particle.connected() returns true before publishing. Doing publish operations from a separate worker thread is another option.

Subscribe

Subscribe to events published by devices.

This allows devices to talk to each other very easily. For example, one device could publish events when a motion sensor is triggered and another could subscribe to these events and respond by sounding an alarm.

You typically call Particle.subscribe() once for each subscription during setup().

A subscription works like a prefix filter. If you subscribe to "foo", you will receive any event whose name begins with "foo", including "foo", "fool", "foobar", and "food/indian/sweet-curry-beans". The maximum length of the subscribe prefix is 64 characters.

You should not call Particle.subscribe() from the constructor of a globally allocated C++ object. See Global Object Constructors for more information.

Each event delivery attempt to a subscription handler uses one Data Operation from your monthly or yearly quota. Setting up the subscription does not use a Data Operations. You should take advantage of the event prefix to avoid delivering events that you do not need. If poor connectivity results in multiple attempts, it could result in multiple Data Operations, up to 3. If the device is currently marked as offline, then no attempt will be made and no Data Operations will be incurred.

If you have multiple devices that subscribe to a hook-response but only want to monitor the response to their own request, as opposed to any device in the account sharing the webhook, you should include the Device ID in the custom hook response as described here. This will assure that you will not consume Data Operations for webhooks intended for other devices.

Particle.subscribe(System.deviceID() + "/hook-response/weather/", myHandler);

• It is possible to receive an event more than once. The most common reason is a lost ACK, which will cause the device to send the event again. Storing a unique identifier in the event payload may help code defensively for this possibility.
• It is possible that events will arrive out-of-order. The most common cause is retransmission, but it can also occur because events can flow through different redundant servers, each with slightly difference latency, so it's possible that two event sent rapidly will arrive out-of-order as well. This is common for multi-part webhook responses.

Subscribe (with content type) - Subscribe

// PROTOTYPES
bool subscribe(const char* name, particle::EventHandlerWithContentType handler);
bool subscribe(const char* name, particle::EventHandlerWithContentTypeFn handler);

typedef void (*EventHandlerWithContentType)(const char* name, const char* data, size_t size, ContentType type);
typedef std::function<void(const char* name, const char* data, size_t size, ContentType type)> EventHandlerWithContentTypeFn;

// EventHandlerWithContentType handler function prototype
void myHandler(const char* name, const char* data, size_t size, ContentType type)

// EventHandler function prototype (classic API)
void myHandler(const char *event_name, const char *data)

The new API passes both a data and a size allowing it to be used with data that contains null bytes, including binary data. The ContentType is also passed to the handler for the handler to use as desired.

Subscribe (with Variant) - Subscribe

If you are expecting structured data, use the subscribe overload that takes a handler with a Variant.

// EXAMPLE
void myHandler(const char* name, Variant data) {
    Log.info("a=%d b=%s", data.get("a").toInt(), data.get("b").toString().c_str());
}

void setup() {
    Particle.subscribe("myEvent", myHandler);
}

If you publish this JSON:

{"a":123,"b":"testing"}

For example, with the Particle CLI:

particle publish myEvent '{"a":123,"b":"testing"}'

The USB serial debug log will show something like:

0000013271 [app] INFO: a=123 b=testing

The prototypes for subscribing to events with a Variant are:

// PROTOTYPES
bool subscribe(const char* name, particle::EventHandlerWithVariant handler);
bool subscribe(const char* name, particle::EventHandlerWithVariantFn handler);

// Handler definitions
typedef void (*EventHandlerWithVariant)(const char* name, EventData data);
typedef std::function<void(const char* name, EventData data)> EventHandlerWithVariantFn;

// EventHandlerWithVariant handler function prototype
void myHandler(const char* name, EventData data);
void myHandler(const char* name, Variant data);

// EventData definition
typedef Variant EventData;

The Variant overload does not have a ContentType because Variant data is always CBOR over-the-air and JSON via webhooks and SSE.

Subscrible (classic API) - Subscribe

SerialLogHandler logHandler;
int i = 0;

void myHandler(const char *event, const char *data)
{
  i++;
  Log.info("%d: event=%s data=%s", i, event, (data ? data : "NULL"));
}

void setup()
{
  Particle.subscribe("temperature", myHandler);
}

To use Particle.subscribe(), define a handler function and register it, typically in setup().

You can register a method in a C++ object as a subscription handler.

#include "Particle.h"

SerialLogHandler logHandler;

class MyClass {
public:
    MyClass();
    virtual ~MyClass();

    void setup();

    void subscriptionHandler(const char *eventName, const char *data);
};

MyClass::MyClass() {
}

MyClass::~MyClass() {
}

void MyClass::setup() {
    Particle.subscribe("myEvent", &MyClass::subscriptionHandler, this);
}

void MyClass::subscriptionHandler(const char *eventName, const char *data) {
    Log.info("eventName=%s data=%s", eventName, data);
}

// In this example, MyClass is a globally constructed object.
MyClass myClass;

void setup() {
    myClass.setup();
}

void loop() {

}

You should not call Particle.subscribe() from the constructor of a globally allocated C++ object. See Global Object Constructors for more information.

Each event delivery attempt to a subscription handler uses one Data Operation from your monthly or yearly quota. Setting up the subscription does not use a Data Operations. You should take advantage of the event prefix to avoid delivering events that you do not need. If poor connectivity results in multiple attempts, it could result in multiple Data Operations, up to 3. If the device is currently marked as offline, then no attempt will be made and no Data Operations will be incurred.

If you have multiple devices that subscribe to a hook-response but only want to monitor the response to their own request, as opposed to any device in the account sharing the webhook, you should include the Device ID in the custom hook response as described here. This will assure that you will not consume Data Operations for webhooks intended for other devices.

Particle.subscribe(System.deviceID() + "/hook-response/weather/", myHandler, MY_DEVICES);

A subscription works like a prefix filter. If you subscribe to "foo", you will receive any event whose name begins with "foo", including "foo", "fool", "foobar", and "food/indian/sweet-curry-beans". The maximum length of the subscribe prefix is 64 characters.

Received events will be passed to a handler function similar to Particle.function(). A subscription handler (like myHandler above) must return void and take two arguments, both of which are C strings (const char *).

• The first argument is the full name of the published event.
• The second argument (which may be NULL) is any data that came along with the event.

Particle.subscribe() returns a bool indicating success. It is OK to register a subscription when the device is not connected to the cloud - the subscription is automatically registered with the cloud next time the device connects.

See special webhook events for more details about handling multipart responses from a webhook in your subscription handler.

• A device can register up to 4 event handlers. This means you can call Particle.subscribe() a maximum of 4 times; after that it will return false. On some versions of Device OS on some devices the limit may be higher.

• Particle.publish() and the Particle.subscribe() handler(s) share the same buffer. As such, calling Particle.publish() within a Particle.subscribe() handler will overwrite the subscribe buffer, corrupting the data! In these cases, copying the subscribe buffer's content to a separate char buffer prior to calling Particle.publish() is recommended.

• You can call Particle.subscribe from setup() or from loop(). The subscription list can be added to at any time, and more than once. The subscriptions are only updated once loop is running, however. During setup() the subscription will not yet be active. Very old versions of Device OS (prior to 1.0.0) may behave differently.

// PROTOTYPES
bool subscribe(const char* name, EventHandler handler);
bool subscribe(const char* name, wiring_event_handler_t handler);

template<typename T>
bool subscribe(const char* name, void (T::*handler)(const char*, const char*), T* instance);

// Handler definitions
typedef void (*EventHandler)(const char *event_name, const char *data);
typedef std::function<void (const char*, const char*)> wiring_event_handler_t;

// Handler function prototype
void eventHandler(const char *event_name, const char *data)

Prior to August 2020, you could subscribe to the public event stream using ALL_DEVICES. This is no longer possible as the public event stream no longer exists. Likewise, MY_DEVICES is no longer necessary as that is the only option now.

// This syntax is no longer necessary
Particle.subscribe("the_event_prefix", theHandler, MY_DEVICES);
Particle.subscribe("the_event_prefix", theHandler, ALL_DEVICES);

• Unclaimed devices can only be used in a product.
• Unclaimed devices can send product events.
• Unclaimed devices can receive function calls and variable requests from the product.
• Unclaimed devices can receive events using Particle.subscribe as of March 2023. This was not previously possible.

The behavior of unclaimed product devices with respect to subscribing to events changed in March 2023:

• Prior to March 2023, claiming was required if the device firmware subscribed to events on-device. This is no longer necessary.
• You still need to claim a device is if you are using a webhook in the sandbox of the user who claimed the device. It is recommended that you use product webhooks instead, which do not require claiming.
• If you are using a device with Mark as Development device, you may want to claim the device to your account so you can easily OTA flash it from Particle Workbench or other development environments.
• If you previously had firmware that subscribed to events but was the device was unclaimed, the events previously disappeared. This is no longer the case and the device will now start receiving those events, and each event will count as a data operation.
• Claiming is still allowed, if you prefer to continue to use claiming, but not recommended.

Additionally:

• Publishes are not end-to-end confirmed. Even if the Particle.publish returns true, there is no guarantee that any recipient (another device, webhook, or SSE) will receive it.
• It is possible to receive an event more than once. The most common reason is a lost ACK, which will cause the device to send the event again. Storing a unique identifier in the event payload may help code defensively for this possibility.
• It is possible that events will arrive out-of-order. The most common cause is retransmission, but it can also occur because events can flow through different redundant servers, each with slightly difference latency, so it's possible that two event sent rapidly will arrive out-of-order as well. This is common for multi-part webhook responses.
• It is possible that even if Particle.publish returns false, the event will still be received by the cloud later. This occurs because the 20-second timeout is reached, so false is returned, but the event is still buffered in Device OS and will be retransmitted if the reconnection to the cloud succeeds.

Future

The Future class is used by Particle.publish to optionally block, and to optionally obtain the success or failure result later.

// EXAMPLE PROTOTYPE
particle::Future<bool> publish(const char* name);

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

// EXAMPLE USAGE 2
bool result = Particle.publish("myEvent");

In example usage 1, the value is not checked, and the call will be asynchronous.

In example usage 2, the value is stored in a bool, and the call will block until completion or timeout.

// Future methods
bool isDone() const;
ResultT result() const;
operator ResultT() const;

It is possible to store the Future<bool> in a variable. This allows the operation to proceed asynchronously, then check later to see if the is operation has completed (isDone()) and what the underlying result was (result()). This is useful if you've implemented your code as finite state machine and you want to not block, transition to the next state, and wait in that state until completion. You'd then transition to another state depending on whether you succeeded or failed.

Note that you may still want to do publishes from a worker thread instead of the main loop, because the Particle.publish function can still block in some cases if there is no network connectivity. For an example, see the background-publish library. This is used by Tracker Edge and Monitor Edge firmware for location publishes.

Ethernet

Note:

By default, Ethernet detection is not done because it will toggle GPIO that may affect circuits that are not using Ethernet. When you select Ethernet during device setup, it is enabled and the setting stored in configuration flash.

It's also possible to enable Ethernet detection from code. This is saved in configuration flash so you don't need to call it every time.

You should call it from setup() but make sure you are using SYSTEM_THREAD(ENABLED) so it can be enabled before the connecting to the cloud. You should not call it from STARTUP().

SYSTEM_THREAD(ENABLED);

void setup() 
{
  System.enableFeature(FEATURE_ETHERNET_DETECTION);
}

Prior to Device OS 5.9.0, interrupt (nINTERRUPT) and reset (nRESET) pins were required to use Ethernet. With Device OS 5.9.0 you can operate without these connected.

If you are using the Adafruit Ethernet Feather Wing (instead of the Particle Feather Wing), by default nRESET and nINTERRUPT pins are not connected. You will either need to connect them (on the small header on the short side) to pins D3 and D4 with jumper wires, or use Device OS 5.9.0 and operate without these two hardware control pins.

¹On the Adafruit Ethernet FeatherWing this pin is not connected by default.

Pin configuration - Ethernet

Since 5.3.0:

In Device OS 5.3.x, it is possible to reconfigure the pins that are used for Ethernet control signals CS, RESET, and INT. This may be desirable if you need to use pins D3-D5 for other purposes, such as SPI1.

In Device OS 5.9.9 and later, it's possible to configure RESET and INT as PIN_INVALID, meaning you are not using hardware reset and interrupt.

The correct order of operations is:

• Start with FEATURE_ETHERNET_DETECTION disabled this will prevent probing the default GPIO that you are using for other purposes, which may have unintended consequences.

• It is recommended that you enable threading and SEMI_AUTOMATIC mode because you will need to execute code before connecting to the cloud.

SYSTEM_THREAD(ENABLED);
SYSTEM_MODE(SEMI_AUTOMATIC);

• If Ethernet.isOn() is false (it's off), then remap the pins. This setting is persistent on reset, cold boot, application firmware flash, and Device OS upgrade. It also is used when in safe mode so Device OS can be upgraded OTA over Ethernet.

if_wiznet_pin_remap remap = {};
remap.base.type = IF_WIZNET_DRIVER_SPECIFIC_PIN_REMAP;
remap.cs_pin = A0;
remap.reset_pin = A2;
remap.int_pin = A1;

auto ret = if_request(nullptr, IF_REQ_DRIVER_SPECIFIC, &remap, sizeof(remap), nullptr);
// ret is SYSTEM_ERROR_NONE on success

• After successful reconfiguration, enable ethernet detection with System.enableFeature(FEATURE_ETHERNET_DETECTION), and then reset the device with System.reset(). This will be fast because the device did not connect to the cloud the first time. This setting is persistent on reset, cold boot, application firmware flash, and Device OS upgrade. It also is used when in safe mode so Device OS can be upgraded OTA over Ethernet.

System.enableFeature(FEATURE_ETHERNET_DETECTION);
System.reset();

In Device OS 6.1.1 and earlier, if you wanted to restore a pin to its default value, you could set it to PIN_INVALID. This is no longer possible as PIN_INVALID is now a usable value for the int_pin for operation without a hardware interrupt pin. You must set it back to the actual default pin to restore default pin mapping.

Here's a full sample application for testing:

// SAMPLE APPLICATION
#include "Particle.h"
SYSTEM_THREAD(ENABLED);
SYSTEM_MODE(SEMI_AUTOMATIC);
Serial1LogHandler log1Handler(115200, LOG_LEVEL_ALL);

retained uint8_t resetRetry = 0;

void setup() {
#if HAL_PLATFORM_WIFI && !HAL_PLATFORM_WIFI_SCAN_ONLY
    // To force Ethernet only, clear Wi-Fi credentials
    Log.info("Clear Wi-Fi credentionals...");
    WiFi.clearCredentials();
#endif // HAL_PLATFORM_WIFI && !HAL_PLATFORM_WIFI_SCAN_ONLY

    // Disable Listening Mode if not required
    if (System.featureEnabled(FEATURE_DISABLE_LISTENING_MODE)) {
        Log.info("FEATURE_DISABLE_LISTENING_MODE enabled");
    } else {
        Log.info("Disabling Listening Mode...");
        System.enableFeature(FEATURE_DISABLE_LISTENING_MODE);
    }

    Log.info("Checking if Ethernet is on...");
    if (Ethernet.isOn()) {
        Log.info("Ethernet is on");
        uint8_t macAddrBuf[8] = {};
        uint8_t* macAddr = Ethernet.macAddress(macAddrBuf);
        if (macAddr != nullptr) {
            Log.info("Ethernet MAC: %02x %02x %02x %02x %02x %02x",
                    macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
        }
        Ethernet.connect();
        waitFor(Ethernet.ready, 30000);
        Log.info("Ethernet.ready: %d", Ethernet.ready());
        resetRetry = 0;
    } else if (++resetRetry <= 3) {
        Log.info("Ethernet is off or not detected, attmpting to remap pins: %d/3", resetRetry);

        if_wiznet_pin_remap remap = {};
        remap.base.type = IF_WIZNET_DRIVER_SPECIFIC_PIN_REMAP;

        remap.cs_pin = D10;
        remap.reset_pin = D6;
        remap.int_pin = D7;

        auto ret = if_request(nullptr, IF_REQ_DRIVER_SPECIFIC, &remap, sizeof(remap), nullptr);
        if (ret != SYSTEM_ERROR_NONE) {
            Log.error("Ethernet GPIO config error: %d", ret);
        } else {
            if (System.featureEnabled(FEATURE_ETHERNET_DETECTION)) {
                Log.info("FEATURE_ETHERNET_DETECTION enabled");
            } else {
                Log.info("Enabling Ethernet...");
                System.enableFeature(FEATURE_ETHERNET_DETECTION);
            }
            delay(500);
            System.reset();
        }
    }

    Particle.connect();
}

void loop() {
    static system_tick_t lastPublish = millis();
    static int count = 0;
    static bool reconnect = false;

    if (Particle.connected()) {
        reconnect = false;
        if (millis() - lastPublish >= 10000UL) {
            Particle.publish("mytest", String(++count), PRIVATE, WITH_ACK);
            lastPublish = millis();
        }
    }

    // Detect a network dropout and reconnect quickly
    if (!reconnect && !Ethernet.ready()) {
        Log.info("Particle disconnect...");
        Particle.disconnect();
        waitFor(Particle.disconnected, 5000);
        Log.info("Network disconnect...");
        Network.disconnect();
        Particle.connect();
        reconnect = true;
    }
}

Muon Ethernet configuration

The following code can be used to enable Ethernet on the Muon. This only needs to be done once and the device must be reset after configuration for the changes to take effect.

// Enable 3V3_AUX
SystemPowerConfiguration powerConfig = System.getPowerConfiguration();
powerConfig.auxiliaryPowerControlPin(D7).interruptPin(A7);
System.setPowerConfiguration(powerConfig);

// Enable Ethernet
if_wiznet_pin_remap remap = {};
remap.base.type = IF_WIZNET_DRIVER_SPECIFIC_PIN_REMAP;

System.enableFeature(FEATURE_ETHERNET_DETECTION);
remap.cs_pin = A3;
remap.reset_pin = PIN_INVALID;
remap.int_pin = A4;
auto ret = if_request(nullptr, IF_REQ_DRIVER_SPECIFIC, &remap, sizeof(remap), nullptr);

M.2 SoM Breakout board Ethernet configuration

The following code can be used to enable Ethernet on the M.2 SoM breakout board. This only needs to be done once and the device must be reset after configuration for the changes to take effect.

// Enable 3V3_AUX
SystemPowerConfiguration powerConfig = System.getPowerConfiguration();
powerConfig.auxiliaryPowerControlPin(D23).interruptPin(A6);
System.setPowerConfiguration(powerConfig);

// Enable Ethernet
if_wiznet_pin_remap remap = {};
remap.base.type = IF_WIZNET_DRIVER_SPECIFIC_PIN_REMAP;

System.enableFeature(FEATURE_ETHERNET_DETECTION);
remap.cs_pin = D5;
remap.reset_pin = PIN_INVALID;
remap.int_pin = PIN_INVALID;
auto ret = if_request(nullptr, IF_REQ_DRIVER_SPECIFIC, &remap, sizeof(remap), nullptr);

on()

Ethernet.on() turns on the Ethernet module. Useful when you've turned it off, and you changed your mind.

Note that Ethernet.on() does not need to be called unless you have changed the system mode or you have previously turned the Ethernet module off.

off()

Ethernet.off() turns off the Ethernet module.

connect()

Attempts to connect to the Ethernet network. When this function returns, the device may not have an IP address on the LAN; use Ethernet.ready() to determine the connection status.

// SYNTAX
Ethernet.connect();

disconnect()

Disconnects from the Ethernet network, but leaves the Ethernet module on.

// SYNTAX
Ethernet.disconnect();

connecting()

This function will return true once the device is attempting to connect, and will return false once the device has successfully connected to the Ethernet network.

// SYNTAX
Ethernet.connecting();

ready()

This function will return true once the device is connected to the network and has been assigned an IP address, which means that it's ready to open TCP sockets and send UDP datagrams. Otherwise it will return false.

// SYNTAX
Ethernet.ready();

In order for Ethernet to be considered ready the Ethernet link must be up, and IP address assigned, DNS configured, and a gateway set. Thus if you using isolated Ethernet (gateway of 0.0.0.0), you cannot use Ethernet.ready() to determine if it's up. This is because Ethernet.ready() implies that it's ready to be used for the cloud connection, which is not true for isolated LANs. If you want to check for isolated LAN up, you can use !Ethernet.connecting() && Ethernet.localIP() != IPAddress()

setConfig() [Ethernet]

Since 5.3.0:

Set a NetworkInterfaceConfig for the Ethernet interface running Device OS 5.3.0 or later. This is used to set a static IP address or restore DHCP addressing (the default).

// PROTOTYPE
int setConfig(const particle::NetworkInterfaceConfig& conf);

// EXAMPLE
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway(SockAddr({192,168,1,1}))
  .dns(SockAddr({192,168,1,1})));

getConfig() [Ethernet]

Since 5.3.0:

Get the current NetworkInterfaceConfig for the Ethernet interface running Device OS 5.3.0 or later.

// PROTOTYPE
particle::NetworkInterfaceConfig getConfig(String profile = String()) const;

prefer() [Ethernet]

Since 5.7.0:

You should normally let automatic connection management handle which network interface to use.

In some cases you may want to prefer cellular or Wi-Fi, and this can be done using the API. Note however:

• The automatic connection management rules still apply.
• The preference only determines which to use if multiple interfaces are available. It will not force connection to a non-available interface.
• Setting a preference does not affect an immediate change if the cloud is currently connected. It will only be consulted on the next automatic connection management which typically occurs after the cloud disconnects.
• Only one network type can be preferred, setting Ethernet.prefer() will clear Cellular.prefer() for example.

// PROTOTYPE
virtual NetworkClass& prefer(bool prefer = true);

// EXAMPLE - enable prefer Ethernet
Ethernet.prefer();

// EXAMPLE - disable prefer Ethernet
Ethernet.prefer(false);

isPreferred() [Ethernet]

Returns true if the preferred network interface is Ethernet. This only indicates that the interface has been preferred and does not reflect what interface is in use.

// PROTOTYPE 
virtual bool isPreferred();

if (Ethernet.isPreferred()) {
    // Do something here
}

listen()

This will enter or exit listening mode, which opens a Serial connection to get Ethernet credentials over USB, and also listens for credentials over Bluetooth.

// SYNTAX - enter listening mode
Ethernet.listen();

Listening mode blocks application code. Advanced cases that use multithreading, interrupts, or system events have the ability to continue to execute application code while in listening mode, and may wish to then exit listening mode, such as after a timeout. Listening mode is stopped using this syntax:

// SYNTAX - exit listening mode
Ethernet.listen(false);

listening()

// SYNTAX
Ethernet.listening();

Returns true if the device is in listening mode (blinking dark blue).

This is only relevant when using SYSTEM_THREAD(ENABLED). When not using threading, listening mode stops user firmware from running, so you would not have an opportunity to test the value and calling this always returns false. With Device OS 6.2.0 and later, system thread is always enabled.

setListenTimeout()

// SYNTAX
Ethernet.setListenTimeout(seconds);

Ethernet.setListenTimeout(seconds) is used to set a timeout value for Listening Mode. Values are specified in seconds, and 0 disables the timeout. By default, Ethernet devices do not have any timeout set (seconds=0). As long as interrupts are enabled, a timer is started and running while the device is in listening mode (Ethernet.listening()==true). After the timer expires, listening mode will be exited automatically. If Ethernet.setListenTimeout() is called while the timer is currently in progress, the timer will be updated and restarted with the new value (e.g. updating from 10 seconds to 30 seconds, or 10 seconds to 0 seconds (disabled)).
Note: Enabling multi-threaded mode with SYSTEM_THREAD(ENABLED) will allow user code to update the timeout value while Listening Mode is active.

Since 1.5.0:

You can also specify a value using chrono literals, for example: Ethernet.setListenTimeout(5min) for 5 minutes.

getListenTimeout()

// SYNTAX
uint16_t seconds = Ethernet.getListenTimeout();

Ethernet.getListenTimeout() is used to get the timeout value currently set for Listening Mode. Values are returned in (uint16_t)seconds, and 0 indicates the timeout is disabled. By default, Ethernet devices do not have any timeout set (seconds=0).

macAddress()

Ethernet.macAddress() gets the MAC address of the Ethernet interface.

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  uint8_t addr[6];
  Ethernet.macAddress(addr);

  Log.info("mac: %02x-%02x-%02x-%02x-%02x-%02x", addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]);
}

localIP()

Ethernet.localIP() is used to get the IP address of the Ethernet interface as an IPAddress.

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  Log.info("localIP: %s", Ethernet.localIP().toString().c_str());
}

subnetMask()

Ethernet.subnetMask() returns the subnet mask of the network as an IPAddress.

SerialLogHandler logHandler;

void setup() {
 // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the subnet mask over Serial.
  Log.info(Ethernet.subnetMask());
}

gatewayIP()

Ethernet.gatewayIP() returns the gateway IP address of the network as an IPAddress.

SerialLogHandler logHandler;

void setup() {
  Serial.begin(9600);
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the gateway IP over Serial.
  Log.info(Ethernet.gatewayIP());
}

dnsServerIP()

Ethernet.dnsServerIP() retrieves the IP address of the DNS server that resolves DNS requests for the device's network connection. This will often be 0.0.0.0.

dhcpServerIP()

Ethernet.dhcpServerIP() retrieves the IP address of the DHCP server that manages the IP address used by the device's network connection. This often will be 0.0.0.0.

WiFi

Wi-Fi Devices (P2, Photon 2, Argon, P1, Photon):

on()

WiFi.on() turns on the Wi-Fi module. Useful when you've turned it off, and you changed your mind.

Note that WiFi.on() does not need to be called unless you have changed the system mode or you have previously turned the Wi-Fi module off.

off()

// EXAMPLE:
Particle.disconnect();
WiFi.off();

WiFi.off() turns off the Wi-Fi module. Useful for saving power, since most of the power draw of the device is the Wi-Fi module.

You must call Particle.disconnect() before turning off the Wi-Fi manually, otherwise the cloud connection may turn it back on again.

This should only be used with SYSTEM_MODE(SEMI_AUTOMATIC) (or MANUAL) as the cloud connection and Wi-Fi are managed by Device OS in AUTOMATIC mode.

connect()

Attempts to connect to the Wi-Fi network. If there are no credentials stored, this will enter listening mode (see below for how to avoid this.). If there are credentials stored, this will try the available credentials until connection is successful. When this function returns, the device may not have an IP address on the LAN; use WiFi.ready() to determine the connection status.

// SYNTAX
WiFi.connect();

Since 0.4.5:

It's possible to call WiFi.connect() without entering listening mode in the case where no credentials are stored:

// SYNTAX
WiFi.connect(WIFI_CONNECT_SKIP_LISTEN);

If there are no credentials then the call does nothing other than turn on the Wi-Fi module.

On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker), prior to Device OS 2.0.0, you needed to call WiFi.on() or Cellular.on() before calling Particle.connect(). This is not necessary on Gen 2 devices (any Device OS version) or with 2.0.0 and later.

On the Argon, starting with Device OS 1.5.0, a quick Wi-Fi scan is done before connecting. The list of available networks is compared with the configured SSIDs. The access point with the strongest signal is connected to. Prior to 1.5.0, only the original access point BSSID that was configured would ever be connected to, even if there was a different access point on the same SSID and network with a stronger signal.

disconnect()

Disconnects from the Wi-Fi network, but leaves the Wi-Fi module on.

// SYNTAX
WiFi.disconnect();

connecting()

This function will return true once the device is attempting to connect using stored Wi-Fi credentials, and will return false once the device has successfully connected to the Wi-Fi network.

// SYNTAX
WiFi.connecting();

ready()

This function will return true once the device is connected to the network and has been assigned an IP address, which means that it's ready to open TCP sockets and send UDP datagrams. Otherwise it will return false.

// SYNTAX
WiFi.ready();

setConfig() [WiFi]

Since 5.3.0:

Set a NetworkInterfaceConfig for the Wi-Fi interface on the Argon, P2, and Photon 2 running Device OS 5.3.0 or later. This is used to set a static IP address or restore DHCP addressing (the default).

// PROTOTYPE
int setConfig(const particle::NetworkInterfaceConfig& conf);

// EXAMPLE
WiFi.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway({192,168,1,1})
  .dns({192,168,1,1});

getConfig() [WiFi]

Since 5.3.0:

Get the current NetworkInterfaceConfig for the Wi-Fi interface on the Argon, P2, and Photon 2 running Device OS 5.3.0 or later.

// PROTOTYPE
particle::NetworkInterfaceConfig getConfig(String profile = String()) const;

selectAntenna() [antenna]

Note:

// SYNTAX
STARTUP(WiFi.selectAntenna(ANT_INTERNAL)); // selects the CHIP antenna
STARTUP(WiFi.selectAntenna(ANT_EXTERNAL)); // selects the u.FL antenna
STARTUP(WiFi.selectAntenna(ANT_AUTO)); // continually switches at high speed between antennas

WiFi.selectAntenna() selects one of three antenna modes. It takes one argument: ANT_AUTO, ANT_INTERNAL or ANT_EXTERNAL.

Note that the antenna selection is remembered even after power off or when entering safe mode. This is to allow your device to be configured once and then continue to function with the selected antenna when applications are flashed that don't specify which antenna to use. Resetting Wi-Fi credentials (long press of MODE) does not clear the antenna selection.

You may specify in code which antenna to use as the default at boot time using the STARTUP() macro. If you are using system thread enabled mode or SEMI_AUTOMATIC or MANUAL system mode, you can select the antenna on setup or loop, however you should not set it continuously.

If no antenna has been previously selected, the ANT_INTERNAL antenna will be chosen by default.

WiFi.selectAntenna() returns 0 on success, or a non-zero error code.

// Use the STARTUP() macro to set the default antenna
// to use system boot time.
// In this case it would be set to the chip antenna
STARTUP(WiFi.selectAntenna(ANT_INTERNAL));

void setup() {
  // your setup code
}

void loop() {
  // your loop code
}

getAntenna()

Note:

// PROTOTYPE
WLanSelectAntenna_TypeDef getAntenna()

This function returns the currently selected antenna, one of:

• ANT_AUTO
• ANT_INTERNAL
• ANT_EXTERNAL

prefer() [WiFi]

Since 5.7.0:

You should normally let automatic connection management handle which network interface to use.

In some cases you may want to prefer cellular or Wi-Fi, and this can be done using the API. Note however:

• The automatic connection management rules still apply.
• The preference only determines which to use if multiple interfaces are available. It will not force connection to a non-available interface.
• Setting a preference does not affect an immediate change if the cloud is currently connected. It will only be consulted on the next automatic connection management which typically occurs after the cloud disconnects.
• Only one network type can be preferred, setting WiFi.prefer() will clear Cellular.prefer() for example.

// PROTOTYPE
virtual NetworkClass& prefer(bool prefer = true);

// EXAMPLE - enable prefer Wi-Fi
WiFi.prefer();

// EXAMPLE - disable prefer Wi-Fi
WiFi.prefer(false);

isPreferred() [WiFi]

Returns true if the preferred network interface is Wi-Fi. This only indicates that the interface has been preferred and does not reflect what interface is in use.

// PROTOTYPE 
virtual bool isPreferred();

if (WiFi.isPreferred()) {
    // Do something here
}

listen()

This will enter or exit listening mode, which opens a Serial connection to get Wi-Fi credentials over USB, and also listens for credentials over Soft AP on the Photon or BLE on the Argon.

// SYNTAX - enter listening mode
WiFi.listen();

Listening mode blocks application code. Advanced cases that use multithreading, interrupts, or system events have the ability to continue to execute application code while in listening mode, and may wish to then exit listening mode, such as after a timeout. Listening mode is stopped using this syntax:

// SYNTAX - exit listening mode
WiFi.listen(false);

listening()

// SYNTAX
WiFi.listening();

Returns true if the device is in listening mode (blinking dark blue).

This is only relevant when using SYSTEM_THREAD(ENABLED). When not using threading, listening mode stops user firmware from running, so you would not have an opportunity to test the value and calling this always returns false. With Device OS 6.2.0 and later, system thread is always enabled.

setListenTimeout()

Since 0.6.1:

// SYNTAX
WiFi.setListenTimeout(seconds);

WiFi.setListenTimeout(seconds) is used to set a timeout value for Listening Mode. Values are specified in seconds, and 0 disables the timeout. By default, Wi-Fi devices do not have any timeout set (seconds=0). As long as interrupts are enabled, a timer is started and running while the device is in listening mode (WiFi.listening()==true). After the timer expires, listening mode will be exited automatically. If WiFi.setListenTimeout() is called while the timer is currently in progress, the timer will be updated and restarted with the new value (e.g. updating from 10 seconds to 30 seconds, or 10 seconds to 0 seconds (disabled)). Note: Enabling multi-threaded mode with SYSTEM_THREAD(ENABLED) will allow user code to update the timeout value while Listening Mode is active.

// EXAMPLE
// If desired, use the STARTUP() macro to set the timeout value at boot time.
STARTUP(WiFi.setListenTimeout(60)); // set listening mode timeout to 60 seconds

void setup() {
  // your setup code
}

void loop() {
  // update the timeout later in code based on an expression
  if (disableTimeout) WiFi.setListenTimeout(0); // disables the listening mode timeout
}

Since 1.5.0:

You can also specify a value using chrono literals, for example: WiFi.setListenTimeout(5min) for 5 minutes.

getListenTimeout()

Since 0.6.1:

// SYNTAX
uint16_t seconds = WiFi.getListenTimeout();

WiFi.getListenTimeout() is used to get the timeout value currently set for Listening Mode. Values are returned in (uint16_t)seconds, and 0 indicates the timeout is disabled. By default, Wi-Fi devices do not have any timeout set (seconds=0).

setCredentials()

Allows the application to set credentials for the Wi-Fi network from within the code. These credentials will be added to the device's memory, and the device will automatically attempt to connect to this network in the future.

• The P2, Photon 2, and Argon remember the 10 most recently set credentials.
• The P2, Photon 2, and M-SoM do not currently support WPA Enterprise.
• The Argon does not support WPA Enterprise.
• The Photon and P1 remember the 5 most recently set credentials.
• The Photon and P1 can store one set of WPA Enterprise credentials in Device OS 0.7.0 and later.

// Connects to an unsecured network.
WiFi.setCredentials(ssid);
WiFi.setCredentials("My_Router_Is_Big");

// Connects to a network secured with WPA2 credentials.
WiFi.setCredentials(ssid, password);
WiFi.setCredentials("My_Router", "mypasswordishuge");

// Connects to a network with a specified authentication procedure.
// Options are WPA2, WPA, or WEP.
WiFi.setCredentials(ssid, password, auth);
WiFi.setCredentials("My_Router", "wepistheworst", WEP);

When used with hidden or offline networks, the security cipher is also required. This is only supported on the Photon and P1. The Argon, P2, and Photon 2 do not support connecting to hidden networks.

// for hidden and offline networks on the Photon, the security cipher is also needed
// Cipher options are WLAN_CIPHER_AES, WLAN_CIPHER_TKIP and WLAN_CIPHER_AES_TKIP
WiFi.setCredentials(ssid, password, auth, cipher);
WiFi.setCredentials("SSID", "PASSWORD", WPA2, WLAN_CIPHER_AES);

// Connects to a network with an authentication procedure specified by WiFiCredentials object
WiFi.setCredentials(credentials);
WiFiCredentials credentials;
credentials.setSsid("My_Router")
           .setSecurity(WEP)
           .setPassword("wepistheworst");
WiFi.setCredentials(credentials);

The password is limited to 64 7-bit ASCII characters. If you pass in a longer password, only the first 64 characters will be saved.

Since 0.7.0:

Note:

Credentials can be set using WiFiCredentials class.

For information on setting up WPA2 Enterprise from the Particle CLI, see this article.

// WPA2 Enterprise with EAP-TLS

// We are setting WPA2 Enterprise credentials
WiFiCredentials credentials("My_Enterprise_AP", WPA2_ENTERPRISE);
// EAP type: EAP-TLS
credentials.setEapType(WLAN_EAP_TYPE_TLS);
// Client certificate in PEM format
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );
// Private key in PEM format
credentials.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\r\n" \
                          /* ... */ \
                          "-----END RSA PRIVATE KEY-----\r\n\r\n"
                         );
// Root (CA) certificate in PEM format (optional)
credentials.setRootCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                               /* ... */ \
                               "-----END CERTIFICATE-----\r\n\r\n"
                              );
// EAP outer identity (optional, default - "anonymous")
credentials.setOuterIdentity("anonymous");
// Save credentials
WiFi.setCredentials(credentials);

// WPA Enterprise with PEAP/MSCHAPv2

// We are setting WPA Enterprise credentials
WiFiCredentials credentials("My_Enterprise_AP", WPA_ENTERPRISE);
// EAP type: PEAP/MSCHAPv2
credentials.setEapType(WLAN_EAP_TYPE_PEAP);
// Set username
credentials.setIdentity("username");
// Set password
credentials.setPassword("password");
// Set outer identity (optional, default - "anonymous")
credentials.setOuterIdentity("anonymous");
// Root (CA) certificate in PEM format (optional)
credentials.setRootCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                               /* ... */ \
                               "-----END CERTIFICATE-----\r\n\r\n"
                              );
// Save credentials
WiFi.setCredentials(credentials);

Parameters:

• ssid: SSID (string)
• password: password (string)
• auth: see SecurityType enum.
• cipher: see WLanSecurityCipher enum.
• credentials: an instance of WiFiCredentials class.

This function returns true if credentials were successfully saved, or false in case of an error.

Note: Setting WPA/WPA2 Enterprise credentials requires use of WiFiCredentials class.

Note: In order for WiFi.setCredentials() to work, the Wi-Fi module needs to be on (if switched off or disabled via non_AUTOMATIC SYSTEM_MODEs call WiFi.on()).

getCredentials()

Since 0.4.9:

Lists the Wi-Fi networks with credentials stored on the device. Returns the number of stored networks.

Note that this returns details about the Wi-Fi networks, but not the actual password.

// DEFINITION
typedef struct WiFiAccessPoint {
   size_t size;
   char ssid[33];
   uint8_t ssidLength;
   uint8_t bssid[6];
   WLanSecurityType security;
   WLanSecurityCipher cipher;
   uint8_t channel;
   int maxDataRate;
   int rssi; 
} WiFiAccessPoint;

// EXAMPLE
LogHandler logHandler;

WiFiAccessPoint ap[5];
int found = WiFi.getCredentials(ap, 5);
for (int i = 0; i < found; i++) {
    Log.info("ssid: %s", ap[i].ssid);
    // security is one of WLAN_SEC_UNSEC, WLAN_SEC_WEP, WLAN_SEC_WPA, WLAN_SEC_WPA2, WLAN_SEC_WPA_ENTERPRISE, WLAN_SEC_WPA2_ENTERPRISE
    Log.info("security: %d", (int) ap[i].security);
    // cipher is one of WLAN_CIPHER_AES, WLAN_CIPHER_TKIP or WLAN_CIPHER_AES_TKIP
    Log.info("cipher: %d", (int) ap[i].cipher);
}

clearCredentials()

This will clear all saved credentials from the Wi-Fi module's memory. This will return true on success and false if the Wi-Fi module has an error.

// SYNTAX
WiFi.clearCredentials();

hasCredentials()

Will return true if there are Wi-Fi credentials stored in the Wi-Fi module's memory.

// SYNTAX
WiFi.hasCredentials();

macAddress()

WiFi.macAddress() returns the MAC address of the device.

// EXAMPLE USAGE
SerialLogHandler logHandler;
byte mac[6];

void setup() {
  WiFi.on();
  // wait up to 10 seconds for USB host to connect
  // requires firmware >= 0.5.3
  waitFor(Serial.isConnected, 10000);

  WiFi.macAddress(mac);

  Log.info("mac: %02x:%02x:%02x:%02x:%02x:%02x", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}

SSID()

WiFi.SSID() returns the SSID of the network the device is currently connected to as a char*.

BSSID()

WiFi.BSSID() retrieves the 6-byte MAC address of the access point the device is currently connected to.

SerialLogHandler logHandler;
byte bssid[6];

void setup() {
  Serial.begin(9600);
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  WiFi.BSSID(bssid);
  Log.info("%02X:%02X:%02X:%02X:%02X:%02X", bssid[0], bssid[1], bssid[2], bssid[3], bssid[4], bssid[5]);
}

RSSI()

WiFi.RSSI() returns the signal strength of a Wi-Fi network from -127 (weak) to -1dB (strong) as an int. Positive return values indicate an error with 1 indicating a Wi-Fi chip error and 2 indicating a time-out error.

// SYNTAX
int rssi = WiFi.RSSI();
WiFiSignal rssi = WiFi.RSSI();

Since 0.8.0

WiFi.RSSI() returns an instance of WiFiSignal class.

// SYNTAX
WiFiSignal sig = WiFi.RSSI();

If you are passing the RSSI value as a variable argument, such as with Serial.printlnf, Log.info, snprintf, etc. make sure you add a cast:

Log.info("RSSI=%d", (int8_t) WiFi.RSSI()).

This is necessary for the compiler to correctly convert the WiFiSignal class into a number.

WiFiSignal Class

This class allows to query a number of signal parameters of the currently connected WiFi network.

getStrength()

Gets the signal strength as a percentage (0.0 - 100.0). See getStrengthValue() on how strength values are mapped to 0%-100% range.

// SYNTAX
WiFiSignal sig = WiFi.RSSI();
float strength = sig.getStrength();

// EXAMPLE
WiFiSignal sig = WiFi.RSSI();
Log.info("WiFi signal strength: %.02f%%", sig.getStrength());

Returns: float

getQuality()

Gets the signal quality as a percentage (0.0 - 100.0). See getQualityValue() on how quality values are mapped to 0%-100% range.

// SYNTAX
WiFiSignal sig = WiFi.RSSI();
float quality = sig.getQuality();

// EXAMPLE
WiFiSignal sig = WiFi.RSSI();
Log.info("WiFi signal quality: %.02f%%", sig.getQuality());

Returns: float

getStrengthValue()

// SYNTAX
WiFiSignal sig = WiFi.RSSI();
float strength = sig.getStrengthValue();

Gets the raw signal strength value in dBm. Range: [-90, 0].

Returns: float

getQualityValue()

// SYNTAX
WiFiSignal sig = WiFi.RSSI();
float quality = sig.getQualityValue();

Gets the raw signal quality value (SNR) in dB. Range: [0, 90].

Returns: float

ping()

WiFi.ping() allows you to ping an IP address and returns the number of packets received as an int. It takes two forms:

WiFi.ping(IPAddress remoteIP) takes an IPAddress and pings that address.

WiFi.ping(IPAddress remoteIP, uint8_t nTries) and pings that address a specified number of times.

Note:

scan()

Returns information about access points within range of the device.

The first form is the simplest, but also least flexible. You provide a array of WiFiAccessPoint instances, and the call to WiFi.scan() fills out the array. If there are more APs detected than will fit in the array, they are dropped. Returns the number of access points written to the array.

// EXAMPLE - retrieve up to 20 Wi-Fi APs
SerialLogHandler logHandler;

WiFiAccessPoint aps[20];
int found = WiFi.scan(aps, 20);
for (int i=0; i<found; i++) {
    WiFiAccessPoint& ap = aps[i];
    Log.info("ssid=%s security=%d channel=%d rssi=%d", ap.ssid, (int)ap.security, (int)ap.channel, ap.rssi);
}

The more advanced call to WiFi.scan() uses a callback function that receives each scanned access point.

// EXAMPLE using a callback
void wifi_scan_callback(WiFiAccessPoint* wap, void* data)
{
    WiFiAccessPoint& ap = *wap;
    Log.info("ssid=%s security=%d channel=%d rssi=%d", ap.ssid, (int)ap.security, (int)ap.channel, ap.rssi);
}

void loop()
{
    int result_count = WiFi.scan(wifi_scan_callback);
    Log.info("result_count=%d", result_count);
}

The main reason for doing this is that you gain access to all access points available without having to know in advance how many there might be.

You can also pass a 2nd parameter to WiFi.scan() after the callback, which allows object-oriented code to be used.

// EXAMPLE - class to find the strongest AP

class FindStrongestSSID
{
    char strongest_ssid[33];
    int strongest_rssi;

    // This is the callback passed to WiFi.scan()
    // It makes the call on the `self` instance - to go from a static
    // member function to an instance member function.
    static void handle_ap(WiFiAccessPoint* wap, FindStrongestSSID* self)
    {
        self->next(*wap);
    }

    // determine if this AP is stronger than the strongest seen so far
    void next(WiFiAccessPoint& ap)
    {
        if ((ap.rssi < 0) && (ap.rssi > strongest_rssi)) {
            strongest_rssi = ap.rssi;
            strcpy(strongest_ssid, ap.ssid);
        }
    }

public:

    /**
     * Scan Wi-Fi Access Points and retrieve the strongest one.
     */
    const char* scan()
    {
        // initialize data
        strongest_rssi = -128;
        strongest_ssid[0] = 0;
        // perform the scan
        WiFi.scan(handle_ap, this);
        return strongest_ssid;
    }
};

// Now use the class
FindStrongestSSID strongestFinder;
const char* ssid = strongestFinder.scan();

}

resolve()

WiFi.resolve() finds the IP address for a domain name.

// SYNTAX
ip = WiFi.resolve(name);

Parameters:

• name: the domain name to resolve (string)

It returns the IP address if the domain name is found, otherwise a blank IP address.

// EXAMPLE USAGE

IPAddress ip;
void setup() {
   ip = WiFi.resolve("www.google.com");
   if(ip) {
     // IP address was resolved
   } else {
     // name resolution failed
   }
}

localIP()

WiFi.localIP() returns the local IP address assigned to the device as an IPAddress.

SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the local IP over Serial.
  Log.info("ip address: %s", WiFi.localIP().toString().c_str());
}

subnetMask()

WiFi.subnetMask() returns the subnet mask of the network as an IPAddress.

SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the subnet mask over Serial.
  Log.info("subnet mask: %s" WiFi.subnetMask().toString().c_str());
}

gatewayIP()

WiFi.gatewayIP() returns the gateway IP address of the network as an IPAddress.

SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the gateway IP over Serial.
  Log.info("gateway: %s", WiFi.gatewayIP().toString().c_str());
}

dnsServerIP()

WiFi.dnsServerIP() retrieves the IP address of the DNS server that resolves DNS requests for the device's network connection.

Note that for this value to be available requires calling Particle.process() after Wi-Fi has connected.

dhcpServerIP()

WiFi.dhcpServerIP() retrieves the IP address of the DHCP server that manages the IP address used by the device's network connection.

Note that for this value to be available requires calling Particle.process() after Wi-Fi has connected.

This API is only used for Gen 2 devices (Photon and P1).

setStaticIP()

Defines the static IP addresses used by the system to connect to the network when static IP is activated.

This API is only available for the Photon and P1 (Gen 2).

On the Argon, P2, and Photon 2, static IP addressing requires Device OS 5.3.0 or later and uses a different API. See NetworkInterfaceConfig.

// SYNTAX

void setup() {
    IPAddress myAddress(192,168,1,100);
    IPAddress netmask(255,255,255,0);
    IPAddress gateway(192,168,1,1);
    IPAddress dns(192,168,1,1);
    WiFi.setStaticIP(myAddress, netmask, gateway, dns);

    // now let's use the configured IP
    WiFi.useStaticIP();
}

The addresses are stored persistently so that they are available in all subsequent application and also in safe mode.

useStaticIP()

Instructs the system to connect to the network using the IP addresses provided to WiFi.setStaticIP()

The setting is persistent and is remembered until WiFi.useDynamicIP() is called.

This API is only available for the Photon and P1 (Gen 2).

On the Argon, P2, and Photon 2, static IP addressing requires Device OS 5.3.0 or later and uses a different API. See NetworkInterfaceConfig.

useDynamicIP()

Instructs the system to connect to the network using a dynamically allocated IP address from the router.

A note on switching between static and dynamic IP. If static IP addresses have been previously configured using WiFi.setStaticIP(), they continue to be remembered by the system after calling WiFi.useDynamicIP(), and so are available for use next time WiFi.useStaticIP() is called, without needing to be reconfigured using WiFi.setStaticIP()

This API is only available for the Photon and P1 (Gen 2).

On the Argon, P2, and Photon 2, static IP addressing requires Device OS 5.3.0 or later and uses a different API. See NetworkInterfaceConfig.

setHostname()

Since 0.7.0:

Sets a custom hostname to be used as DHCP client name (DHCP option 12).

Parameters:

• hostname: the hostname to set (string)

// SYNTAX

WiFi.setHostname("photon-123");

By default the device uses its device ID as hostname.

The hostname is stored in persistent memory. In order to reset the hostname to its default value (device ID) setHostname() needs to be called with hostname argument set to NULL.

// Reset hostname to default value (device ID)
WiFi.setHostname(NULL);
// Both these functions should return the same value.
Serial.println(WiFi.getHostname());
Serial.println(System.deviceID());

Hostname setting is only available on the Photon and P1 (Gen 2). It is not available on the Argon or Ethernet (Gen 3), P2, or Photon 2.

hostname()

Since 0.7.0:

Retrieves device hostname used as DHCP client name (DHCP option 12).

This function does not take any arguments and returns a String.

// SYNTAX
String hostname = WiFi.hostname();

By default the device uses its device ID as hostname. See WiFi.setHostname() for documentation on changing the hostname.

Hostname setting is only available on the Photon and P1 (Gen 2). It is not available on the Argon or Ethernet (Gen 3), P2, or Photon 2.

wlan_get_country_code

Since 5.0.0:

Gets the Wi-Fi country code or region code. The default is WLAN_CC_US. This is not automatically set; if you need to use a different country code it must be set manually.

// PROTOTYPE
int wlan_get_country_code(void* reserved);

// EXAMPLE
wlan_country_code_t ccType = wlan_get_country_code(nullptr);

See the list of code in wlan_set_country_code.

This API is available only on the P2, Photon 2, and M-SoM in Device OS 5.0.0 and later.

wlan_set_country_code

Since 5.0.0:

Sets the Wi-Fi country code or region code. The default is WLAN_CC_US. This is not automatically set; you must manually set it if the country you are using the device in requires setting a specific Wi-Fi channel plan. The setting is stored in the DCT (configration flash memory) and is not reset when flashing user firmware, Device OS, or when clearing Wi-Fi credentials.

// PROTOTYPE
int wlan_set_country_code(wlan_country_code_t country, void* reserved);

// EXAMPLE
wlan_set_country_code(wlan_country_code_t::WLAN_CC_JP, nullptr);

This API is available only on the P2, Photon 2, and M-SoM in Device OS 5.0.0 and later.

This setting is stored at the DCT offset DCT_COUNTRY_CODE_OFFSET (country_code, offset 1758, 2 bytes) and thus can also be set in DFU mode using the -a 1 to store in alt bank 1 (DCT).

WiFiCredentials class

This class allows to define WiFi credentials that can be passed to WiFi.setCredentials() function.

// EXAMPLE - defining and using WiFiCredentials class

void setup() {
    // Ensure that WiFi module is on
    WiFi.on();
    // Set up WPA2 access point "My AP" with password "mypassword" and AES cipher
    WiFiCredentials credentials("My AP", WPA2);
    credentials.setPassword("mypassword")
               .setCipher(WLAN_CIPHER_AES);
    // Connect if settings were successfully saved
    if (WiFi.setCredentials(credentials)) {
        WiFi.connect();
        waitFor(WiFi.ready, 30000);
        Particle.connect();
        waitFor(Particle.connected, 30000);
    }
}

void loop() {
}

WiFiCredentials()

Constructs an instance of the WiFiCredentials class. By default security type is initialized to unsecured (UNSEC).

// SYNTAX
WiFiCredentials credentials(SecurityType security = UNSEC); // 1
WiFiCredentials credentials(const char* ssid, SecurityType security = UNSEC); // 2

// EXAMPLE - constructing WiFiCredentials instance
// Empty instance, security is set to UNSEC
WiFiCredentials credentials;
// No SSID, security is set to WPA2
WiFiCredentials credentials(WPA2);
// SSID set to "My AP", security is set to UNSEC
WiFiCredentials credentials("My AP");
// SSID set to "My WPA AP", security is set to WPA
WiFiCredentials credentials("My AP", WPA);

Parameters:

• ssid: SSID (string)
• security: see SecurityType enum.

setSsid()

Sets access point SSID.

// SYNTAX
WiFiCredentials& WiFiCredentials::setSsid(const char* ssid);

// EXAMPLE - setting ssid
WiFiCredentials credentials;
credentials.setSsid("My AP");

Parameters:

• ssid: SSID (string)

setSecurity()

Sets access point security type.

// SYNTAX
WiFiCredentials& WiFiCredentials::setSecurity(SecurityType security);

// EXAMPLE - setting security type
WiFiCredentials credentials;
credentials.setSecurity(WPA2);

Parameters:

• security: see SecurityType enum.

setCipher()

Sets access point cipher.

// SYNTAX
WiFiCredentials& WiFiCredentials::setCipher(WLanSecurityCipher cipher);

// EXAMPLE - setting cipher
WiFiCredentials credentials;
credentials.setCipher(WLAN_CIPHER_AES);

Parameters:

• cipher: see WLanSecurityCipher enum.

setPassword()

Sets access point password.

When configuring credentials for WPA/WPA2 Enterprise access point with PEAP/MSCHAPv2 authentication, this function sets password for username set by setIdentity().

// SYNTAX
WiFiCredentials& WiFiCredentials::setPassword(const char* password);

// EXAMPLE - setting password
WiFiCredentials credentials("My AP", WPA2);
credentials.setPassword("mypassword");

Parameters:

• password: WEP/WPA/WPA2 access point password, or user password for PEAP/MSCHAPv2 authentication (string)

The password is limited to 64 7-bit ASCII characters. If you pass in a longer password, only the first 64 characters will be saved.

setHidden()

Since 5.5.0:

Allows connecting to a Wi-Fi network with a hidden SSID.

Normally, the P2, Photon 2, M-SoM, and Argon do a Wi-Fi scan and compare this against the list of configured networks to choose a network to connect to. If no connection made to non-hidden networks, then an attempt is made to connect to each hidden network. This will be slower, as each connection attempt needs to time out.

// PROTOTYPE
virtual WiFiCredentials& setHidden(bool hidden = true) 

// EXAMPLE
WiFiCredentials creds;
creds.setSsid("My Secret Network");
creds.setPassword("secret");
creds.setSecurity(SecurityType::WPA2);
creds.setHidden(true);
WiFi.setCredentials(creds);

setValidate()

Since 5.8.0:

When set, validate that the Wi-Fi network can be connected to before setting the credentials. The default is to save without validating when using WiFi.setCredentials().

If Wi-Fi is off, it will be turned on to validate credentials.

If Wi-Fi is on and connected, the current network will be disconnected (including the cloud connection, if connected) to attempt to connect to the new network.

// PROTOTYPE
virtual WiFiCredentials& setValidate(bool validate = true)

// EXAMPLE
WiFiCredentials creds;
creds.setSsid("My Network");
creds.setPassword("secret");
creds.setSecurity(SecurityType::WPA2);
creds.setValidate(true);
WiFi.setCredentials(creds);

setChannel()

Sets access point channel.

// SYNYAX
WiFiCredentials& WiFiCredentials::setChannel(int channel);

// EXAMPLE - setting channel
WiFiCredentials credentials("My AP");
credentials.setChannel(10);

Parameters:

• channel: WLAN channel (int)

setEapType()

Sets EAP type.

// SYNTAX
WiFiCredentials& WiFiCredentials::setEapType(WLanEapType type);

// EXAMPLE - setting EAP type
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setEapType(WLAN_EAP_TYPE_PEAP);

Parameters:

• type: EAP type. See WLanEapType enum for a list of supported values.

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setIdentity()

Sets EAP inner identity (username in case of PEAP/MSCHAPv2).

// SYNTAX
WiFiCredentials& WiFiCredentials::setIdentity(const char* identity);

// EXAMPLE - setting PEAP identity (username)
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setEapType(WLAN_EAP_TYPE_PEAP);
credentials.setIdentity("username");

Parameters:

• identity: inner identity (string)

setOuterIdentity()

Sets EAP outer identity. Defaults to "anonymous".

// SYNTAX
WiFiCredentials& WiFiCredentials::setOuterIdentity(const char* identity);

// EXAMPLE - setting outer identity
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setOuterIdentity("notanonymous");

Parameters:

• identity: outer identity (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setClientCertificate()

Sets client certificate used for EAP-TLS authentication.

// SYNTAX
WiFiCredentials& WiFiCredentials::setClientCertificate(const char* cert);

// EXAMPLE - setting client certificate
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );

Parameters:

• cert: client certificate in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setPrivateKey()

Sets private key used for EAP-TLS authentication.

// SYNTAX
WiFiCredentials& WiFiCredentials::setPrivateKey(const char* key);

// EXAMPLE - setting private key
WiFiCredentials credentials;
credentials.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\r\n" \
                          /* ... */ \
                          "-----END RSA PRIVATE KEY-----\r\n\r\n"
                         );

Parameters:

• key: private key in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setRootCertificate()

Sets one more root (CA) certificates.

// SYNTAX
WiFiCredentials& WiFiCredentials::setRootCertificate(const char* cert);

// EXAMPLE - setting one root certificate
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );
// EXAMPLE - setting multiple root certificates
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n"
                                 "-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );

Parameters:

• cert: one or multiple concatenated root certificates in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

WLanEapType Enum

This enum defines EAP types.

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

SecurityType Enum

This enum defines wireless security types.

WLanSecurityCipher Enum

This enum defines wireless security ciphers.

Tether

Since 6.2.0:

Tethering allows another device to use the cellular network of certain Particle devices. See tethering for more information.

TetherSerialConfig

The TetherSerialConfig class configures the serial port parameters for the Tethering PPP connection.

serial - TetherSerialConfig

Select the hardware serial port to use for the tethering PPP connection. This must be a hardware serial port (not a USB serial port) and hardware flow control (RTS/CTS) is recommended.

// EXAMPLE
Tether.bind(TetherSerialConfig().baudrate(921600).serial(Serial1));

// PROTOTYPES
TetherSerialConfig& serial(USARTSerial& s);
USARTSerial& serial() const;

config - TetherSerialConfig

Select serial port configuration options. The values depend on the device and port.

The default is SERIAL_8N1 | SERIAL_FLOW_CONTROL_RTS_CTS.

// PROTOTYPES
TetherSerialConfig& config(unsigned conf);
unsigned config() const;

baudrate - TetherSerialConfig

Select the hardware serial port baud rate to use for the tethering PPP connection.

The default is 921600.

// EXAMPLE
Tether.bind(TetherSerialConfig().baudrate(921600).serial(Serial1));

// PROTOTYPES
TetherSerialConfig& baudrate(unsigned baud);
unsigned baudrate() const;

on() - Tether

Tether.on() turns on the tethering support. It defaults to off.

// EXAMPLE
Tether.bind(TetherSerialConfig().baudrate(921600).serial(Serial1));
Tether.on();
Tether.connect();

off() - Tether

Tether.off() turns off tethering support.

connect() - Tether

Starts the PPP server so the other device can send requests to it. You will typically turn it on, then connect, after connecting to cellular.

// EXAMPLE
Tether.bind(TetherSerialConfig().baudrate(921600).serial(Serial1));
Tether.on();
Tether.connect();

// SYNTAX
Tether.connect();

disconnect() - Tether

Disconnects from the tethering, but leaves it on.

// SYNTAX
Tether.disconnect();

connecting() - Tether

This function will return true while the PPP server is starting up, and false once running.

// SYNTAX
Tether.connecting();

ready() - Tether

This function will return true once PPP server is running and can accept requests from the other device. Otherwise it will return false.

// SYNTAX
Tether.ready();

localIP() - Tether

Tether.localIP() is used to get the IP address of the PPP server as an IPAddress.

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  Log.info("localIP: %s", Tether.localIP().toString().c_str());
}

subnetMask() - Tether

Tether.subnetMask() returns the subnet mask of the PPP server as an IPAddress.

SerialLogHandler logHandler;

void setup() {
 // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the subnet mask over Serial.
  Log.info(Tether.subnetMask());
}

gatewayIP() - Tether

Tether.gatewayIP() returns the gateway IP address of the PPP server as an IPAddress.

SerialLogHandler logHandler;

void setup() {
  Serial.begin(9600);
  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  // Prints out the gateway IP over Serial.
  Log.info(Tether.gatewayIP());
}

Network

The Network class can be used instead of Cellular or WiFi and represents the set of features common across all supported networking types: Cellular, Wi-Fi, and Ethernet.

There are two common uses for this:

• When you have code that runs on both Wi-Fi and Cellular devices, and you want to work automatically with the default network interface without having to use #ifdef.
• When you are writing a library or module within a large application and want to be able to work with a specific interface that is decided on by the caller.

// EXAMPLE
#include "Particle.h"

SYSTEM_THREAD(ENABLED);
SerialLogHandler logHandler;

class ExampleModule {
public:
    ExampleModule &withNetwork(NetworkClass &network) {
        this->network = network;
        return *this;
    }

    void setup() {        
    }

    void loop() {
        bool ready = network.ready();
        if (ready != lastReady) {
            lastReady = ready;
            Log.info("ready=%d", (int) ready);
        }
    }

    NetworkClass &network = Network;
    bool lastReady = false;
};
ExampleModule exampleModule;

void setup() {
    exampleModule
        .withNetwork(Ethernet)
        .setup();
}

void loop() {
    exampleModule.loop();
}

This example prints when the network changes to or from ready state. By default, it uses Network, the default networking for this device. However, the caller can use the withNetwork() method to pass in a different network. In this example, it changes the behavior to monitor the Ethernet network instead.

When using the switchable network, it uses network (lowercase, the member variable), instead of Network (default interface), or a specific interface like Cellular or WiFi.

on() [Network]

Network.on() turns on the the default network interface for this device, typically Cellular or Wi-Fi.

Note that Network.on() does not need to be called unless you have changed the system mode or you have previously turned the network off.

off() [Network]

// EXAMPLE:
Particle.disconnect();
Network.off();

Network.off() turns off the default network interface for this device, typically Cellular or Wi-Fi.

You must call Particle.disconnect() before turning off the network manually, otherwise the cloud connection may turn it back on again.

This should only be used with SYSTEM_MODE(SEMI_AUTOMATIC) (or MANUAL) as the cloud connection and Wi-Fi are managed by Device OS in AUTOMATIC mode.

connect() [Network]

Attempts to connect to default network interface for this device, typically Cellular or Wi-Fi.

For Wi-Fi devices, if there are no credentials stored, this will enter listening mode, blinking dark blue. If there are credentials stored, this will try the available credentials until connection is successful. When this function returns, the device may not have an IP address on the LAN; use Network.ready() to determine the connection status.

// SYNTAX
Network.connect();

On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker), prior to Device OS 2.0.0, you needed to call WiFi.on() or Cellular.on() before calling Particle.connect(). This is not necessary on Gen 2 devices (any Device OS version) or with 2.0.0 and later.

On the Argon, starting with Device OS 1.5.0, a quick Wi-Fi scan is done before connecting. The list of available networks is compared with the configured SSIDs. The access point with the strongest signal is connected to. Prior to 1.5.0, only the original access point BSSID that was configured would ever be connected to, even if there was a different access point on the same SSID and network with a stronger signal.

disconnect() [Network]

Disconnects from the network, but leaves the network module on.

// SYNTAX
Network.disconnect();

connecting() [Network]

This function will return true once the device is attempting to connect, and will return false once the device has successfully connected to the network.

// SYNTAX
Network.connecting();

ready() [Network]

This function will return true once the device is connected to the network. Otherwise it will return false.

// SYNTAX
Network.ready();

setConfig() [Network]

Since 5.3.0:

Set a NetworkInterfaceConfig for a generic network interface on the Argon, P2, and Photon 2 running Device OS 5.3.0 or later. This can be used with Ethernet and WiFi. This is used to set a static IP address or restore DHCP addressing (the default).

// PROTOTYPE
int setConfig(const particle::NetworkInterfaceConfig& conf);

// EXAMPLE
Network.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway(SockAddr({192,168,1,1}))
  .dns(SockAddr({192,168,1,1})));

getConfig() [Network]

Since 5.3.0:

Get the current NetworkInterfaceConfig for a generic network interface interface on the Argon, P2, and Photon 2 running Device OS 5.3.0 or later. This can be used with Ethernet and WiFi.

// PROTOTYPE
particle::NetworkInterfaceConfig getConfig(String profile = String()) const;

prefer() [Network]

Since 5.7.0:

You should normally let automatic connection management handle which network interface to use. There are prefer() methods in the Cellular, WiFi, and Ethernet classes that can be used if you have a need to steer the connection management toward a specific interface.

• The automatic connection management rules still apply when preferring an interface.
• The preference only determines which to use if multiple interfaces are available. It will not force connection to a non-available interface.
• Setting a preference does not affect an immediate change if the cloud is currently connected. It will only be consulted on the next automatic connection management which typically occurs after the cloud disconnects.
• Only one network type can be preferred, setting WiFi.prefer() will clear Cellular.prefer() for example.
• Setting Network as the preferred interface will clear other preferences such as WiFi and Cellular.

// PROTOTYPE
virtual NetworkClass& prefer(bool prefer = true);

// EXAMPLE - Enable automatic connection management (disable other preferences)
Network.prefer();

isPreferred() [Network]

Since 5.6.0:

Returns true if automatic connection management is in use, which is to say that no other interfaces such as WiFi and Cellular have been selected as preferred.

// PROTOTYPE 
virtual bool isPreferred();

if (Network.isPreferred()) {
    // Automatic connection management is enabled
}

listen() [Network]

This will enter or exit listening mode, blinking dark blue. The cloud connection is not available in listening mode.

// SYNTAX - enter listening mode
Network.listen();

Listening mode blocks application code. Advanced cases that use multithreading, interrupts, or system events have the ability to continue to execute application code while in listening mode, and may wish to then exit listening mode, such as after a timeout. Listening mode is stopped using this syntax:

// SYNTAX - exit listening mode
Network.listen(false);

listening() [Network]

// SYNTAX
Network.listening();

Returns true if the device is in listening mode (blinking dark blue).

This is only relevant when using SYSTEM_THREAD(ENABLED). When not using threading, listening mode stops user firmware from running, so you would not have an opportunity to test the value and calling this always returns false. With Device OS 6.2.0 and later, system thread is always enabled.

setListenTimeout() [Network]

Since 0.6.1:

// SYNTAX
Network.setListenTimeout(seconds);

Network.setListenTimeout(seconds) is used to set a timeout value for Listening Mode. Values are specified in seconds, and 0 disables the timeout. This function is rarely needed.

// EXAMPLE
// If desired, use the STARTUP() macro to set the timeout value at boot time.
STARTUP(Network.setListenTimeout(60)); // set listening mode timeout to 60 seconds

void setup() {
  // your setup code
}

void loop() {
  // update the timeout later in code based on an expression
  if (disableTimeout) Network.setListenTimeout(0); // disables the listening mode timeout
}

Since 1.5.0:

You can also specify a value using chrono literals, for example: Network.setListenTimeout(5min) for 5 minutes.

getListenTimeout() [Network]

Since 0.6.1:

// SYNTAX
uint16_t seconds = Network.getListenTimeout();

Network.getListenTimeout() is used to get the timeout value currently set for Listening Mode. Values are returned in (uint16_t)seconds, and 0 indicates the timeout is disabled. This function is rarely needed.

NetworkInterfaceConfig

Since 5.3.0:

With Device OS 5.3.0 and later, this class is used to hold a configuration for network interface addresses, typically to enable static IP addressing for Ethernet or Wi-Fi instead of using DHCP.

NetworkInterfaceConfig::source

Sets the network interface to DHCP (the default), or static IP addressing. The setting is persistent and saved in the flash file system.

• NetworkInterfaceConfigSource::DHCP
• NetworkInterfaceConfigSource::STATIC

// PROTOTYPES
NetworkInterfaceConfig& source(NetworkInterfaceConfigSource source, int family = AF_INET);
NetworkInterfaceConfigSource source(int family = AF_INET) const;

// EXAMPLE - Restore DHCP addressing for Ethernet
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::DHCP);

NetworkInterfaceConfig::address

Sets the IP address when using static IP addressing. The setting is persistent and saved in the flash file system.

Typically you use the last overload which takes two IPAddress class references, one for the address and one for the subnet mask.

Note that the syntax {192,168,1,20} uses commas, not the more typical period or dot, because this is a C++ initializer, not a string.

// PROTOTYPES
NetworkInterfaceConfig& address(const NetworkInterfaceAddress& addr);
NetworkInterfaceConfig& address(SockAddr addr, SockAddr mask);
NetworkInterfaceConfig& address(IPAddress addr, IPAddress mask);

// EXAMPLE
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0}));

NetworkInterfaceConfig::gateway

Sets the gateway IP address when using static IP addressing. The setting is persistent and saved in the flash file system.

Even though the parameter is a SockAddr, you can initialize the gateway address as if it were an IPAddress.

Note that the syntax {192,168,1,1} uses commas, not the more typical period or dot, because this is a C++ initializer, not a string.

When using Ethernet, if the link is active and the gateway is reachable, by default the Ethernet interface is the default route, including for the cloud connection, even if the Ethernet LAN is not connected to the Internet (isolated LAN). To prevent this behavior with Device OS 5.3.0 and later, set the gateway to {0,0,0,0} which will prevent the Ethernet interface from being used to access the Internet, including the Particle cloud. This can be done for both static and DHCP addressing. You can still access hosts on the Ethernet local LAN by TCP or UDP. You might do this for an isolated LAN that has Modbus TCP devices on it, for example. For more information, see Isolated LAN.

// PROTOTYPES
NetworkInterfaceConfig& gateway(SockAddr addr);
SockAddr gateway(int family = AF_INET) const;

// EXAMPLE
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway(SockAddr({192,168,1,1})));

// EXAMPLE - Ethernet is isolated, do not use for Internet or cloud access
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway(SockAddr({0,0,0,0})));

// EXAMPLE - Ethernet is isolated, do not use for Internet or cloud access but does have a DHCP server
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::DHCP)
  .gateway(SockAddr({0,0,0,0})));

NetworkInterfaceConfig::dns

Sets the DNS server address. The setting is persistent and saved in the flash file system. You can set multiple DNS server addresses if desired.

Even though the parameter is a SockAddr, you can initialize the gateway address as if it were an IPAddress.

// PROTOTYPE
NetworkInterfaceConfig& dns(SockAddr dns);

// EXAMPLE
Ethernet.setConfig(NetworkInterfaceConfig()
  .source(NetworkInterfaceConfigSource::STATIC)
  .address({192,168,1,20}, {255,255,255,0})
  .gateway(SockAddr({192,168,1,1}))
  .dns(SockAddr({192,168,1,1}))
  .dns(SockAddr({8,8,8,8})));

SoftAP HTTP pages

Note:

Since 0.5.0:

When the device is in listening mode, it creates a temporary access point (AP) and a HTTP server on port 80. The HTTP server is used to configure the Wi-Fi access points the device attempts to connect to. As well as the system providing HTTP URLs, applications can add their own pages to the SoftAP HTTP server.

SoftAP HTTP Pages is presently an advanced feature, requiring moderate C++ knowledge. To begin using the feature:

• add #include "Particle.h" below that, then
• add #include "softap_http.h" below that still

// SYNTAX

void myPages(const char* url, ResponseCallback* cb, void* cbArg, Reader* body, Writer* result, void* reserved);

STARTUP(softap_set_application_page_handler(myPages, nullptr));

The softap_set_application_page_handler is set during startup. When the system is in setup mode (listening mode, blinking dark blue), and a request is made for an unknown URL, the system calls the page handler function provided by the application (here, myPages.)

The page handler function is called whenever an unknown URL is requested. It is called with these parameters:

• url: the path of the file requested by the client. It doesn't include the server name or port. Examples: /index, /someimage.jpg.
• cb: a response callback - this is used by the application to indicate the type of HTTP response, such as 200 (OK) or 404 (not found). More on this below.
• cbArg: data that should be passed as the first parameter to the callback function cb.
• body: a reader object that the page handler uses to retrieve the HTTP request body
• result: a writer object that the page handler uses to write the HTTP response body
• reserved: reserved for future expansion. Will be equal to nullptr and can be ignored.

The application MUST call the page callback function cb to provide a response for the requested page. If the requested page url isn't recognized by the application, then a 404 response should be sent, as described below.

The page callback function

When your page handler function is called, the system passes a result callback function as the cb parameter. The callback function takes these parameters:

• cbArg: this is the cbArg parameter passed to your page callback function. It's internal state used by the HTTP server.
• flags: presently unused. Set to 0.
• status: the HTTP status code, as an integer, such as 200 for OK, or 404 for page not found.
• mime-type: the mime-type of the response as a string, such as text/html or application/javascript.
• header: an optional pointer to a Header that is added to the response sent to the client.

For example, to send a "not found" error for a page that is not recognized, your application code would call

//  EXAMPLE - send a 404 response for an unknown page
cb(cbArg, 0, 404, "text/plain", nullptr);

Retrieving the request data

When the HTTP request contains a request body (such as with a POST request), the Reader object provided by the body parameter can be used to retrieve the request data.

// EXAMPLE

if (body->bytes_left) {
    char* data = body->fetch_as_string();
    // handle the body data
     dostuff(data);
     // free the data! IMPORTANT!
     free(data);
}

Sending a response

When sending a page, the page function responds with a HTTP 200 code, meaning the content was found, followed by the page data.

// EXAMPLE - send a page

if (!stricmp(url, '/helloworld') {
    // send the response code 200, the mime type "text/html"
    cb(cbArg, 0, 200, "text/html", nullptr);
    // send the page content
    result->write("<h2>hello world!</h2>");
}

The default page

When a browser requests the default page (http://192.168.0.1/) the system internally redirects this to /index so that it can be handled by the application.

The application may provide an actual page at /index or redirect to another page if the application prefers to have another page as its launch page.

Sending a redirect

The application can send a redirect response for a given page in order to manage the URL namespace, such as providing aliases for some resources.

The code below sends a redirect from the default page /index to /index.html

// EXAMPLE - redirect from /index to /index.html
// add this code in the page hanler function

if (strcmp(url,"/index")==0) {
    Header h("Location: /index.html\r\n");
    cb(cbArg, 0, 301, "text/plain", &h);
    return;
}

Complete example

The example source code can be downloaded here.

Here's a complete example providing a Web UI for setting up WiFi via HTTP. Credit for the HTTP pages goes to GitHub user @mebrunet! (Included from PR #909 here) (Source code here)

Cellular

Cellular Devices (B-Series SoM, Tracker SoM, Tracker One, Boron, E404X, E-Series, and Electron):

on()

Cellular.on() turns on the Cellular module. Useful when you've turned it off, and you changed your mind.

Note that Cellular.on() does not need to be called unless you have changed the system mode or you have previously turned the Cellular module off. When turning on the Cellular module, it will go through a full re-connect to the Cellular network which will take anywhere from 30 to 60 seconds in most situations.

// SYNTAX
Cellular.on();

Note: Cellular.on() API is non-blocking on all platforms except for Electron with threading disabled.

Since 2.1.0:

Cellular.isOn() can be used to actively wait for when the modem gets powered on. Alternatively network system events can be used to track the power state of the modem.

off()

Cellular.off() turns off the Cellular module. Useful for saving power, since most of the power draw of the device is the Cellular module. Note: turning off the Cellular module will force it to go through a full re-connect to the Cellular network the next time it is turned on.

// SYNTAX
Cellular.off();

// EXAMPLE
Particle.disconnect();
Cellular.off();

You must not turn off and on cellular more than every 10 minutes (6 times per hour). Your SIM can be blocked by your mobile carrier for aggressive reconnection if you reconnect to cellular very frequently.

If you are manually managing the cellular connection in case of connection failures, you should wait at least 5 minutes before stopping the connection attempt. When retrying on failure, you should implement a back-off scheme waiting 5 minutes, 10 minutes, 15 minutes, 20 minutes, 30 minutes, then 60 minutes between retries. Repeated failures to connect can also result in your SIM being blocked.

You must call Particle.disconnect() before turning off the cellular modem manually, otherwise the cloud connection may turn the cellular modem back on.

This should only be used with SYSTEM_MODE(SEMI_AUTOMATIC) (or MANUAL) as the cloud connection and cellular modem are managed by Device OS in AUTOMATIC mode.

Note: Cellular.off() API is non-blocking on all platforms except for Electron with threading disabled.

Since 2.1.0:

Cellular.isOff() can be used to actively wait for when the modem gets powered off. Alternatively network system events can be used to track the power state of the modem.

isOn()

Since 2.1.0:

This function will return true if the cellular modem is powered on and went through low level initialization. Otherwise it will return false.

// SYNTAX
Cellular.isOn();

// EXAMPLE
Cellular.on();
waitFor(Cellular.isOn, 30000);

isOff()

Since 2.1.0:

This function will return true if the cellular modem is powered off. Otherwise it will return false.

// SYNTAX
Cellular.isOff();

// EXAMPLE
Cellular.off();
waitFor(Cellular.isOff, 60000);

connect()

Attempts to connect to the Cellular network. If there are no credentials entered, the default Particle APN for Particle SIM cards will be used. If no SIM card is inserted, the device will enter listening mode. If a 3rd party APN is set, these credentials must match the inserted SIM card for the device to connect to the cellular network. When this function returns, the device may not have a local (private) IP address; use Cellular.ready() to determine the connection status.

// SYNTAX
Cellular.connect();

On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker), prior to Device OS 2.0.0, you needed to call WiFi.on() or Cellular.on() before calling Particle.connect(). This is not necessary on Gen 2 devices (any Device OS version) or with 2.0.0 and later.

disconnect()

Disconnects from the Cellular network, but leaves the Cellular module on.

// SYNTAX
Cellular.disconnect();

connecting()

This function will return true once the device is attempting to connect using the default Particle APN or 3rd party APN cellular credentials, and will return false once the device has successfully connected to the cellular network.

// SYNTAX
Cellular.connecting();

ready()

This function will return true once the device is connected to the cellular network and has been assigned an IP address, which means it has an activated PDP context and is ready to open TCP/UDP sockets. Otherwise it will return false.

// SYNTAX
Cellular.ready();

prefer() [Cellular]

Since 5.7.0:

You should normally let automatic connection management handle which network interface to use.

In some cases you may want to prefer cellular, Wi-Fi, or Ethernet, and this can be done using the API. Note however:

• The automatic connection management rules still apply.
• The preference only determines which to use if multiple interfaces are available. It will not force connection to a non-available interface.
• Setting a preference does not affect an immediate change if the cloud is currently connected. It will only be consulted on the next automatic connection management which typically occurs after the cloud disconnects.
• Only one network type can be preferred, setting Cellular.prefer() will clear WiFi.prefer() for example.

// PROTOTYPE
virtual NetworkClass& prefer(bool prefer = true);

// EXAMPLE - enable prefer cellular
Cellular.prefer();

// EXAMPLE - disable prefer cellular
Cellular.prefer(false);

isPreferred() [Cellular]

Returns true if the preferred network interface is cellular. This only indicates that the interface has been preferred and does not reflect what interface is in use.

// PROTOTYPE 
virtual bool isPreferred();

if (Cellular.isPreferred()) {
    // Do something here
}

listen()

This will enter or exit listening mode, which opens a Serial connection to get Cellular information such as the IMEI or CCID over USB.

// SYNTAX - enter listening mode
Cellular.listen();

Listening mode blocks application code. Advanced cases that use multithreading, interrupts, or system events have the ability to continue to execute application code while in listening mode, and may wish to then exit listening mode, such as after a timeout. Listening mode is stopped using this syntax:

// SYNTAX - exit listening mode
Cellular.listen(false);

listening()

// SYNTAX
Cellular.listening();

Returns true if the device is in listening mode (blinking dark blue).

This is only relevant when using SYSTEM_THREAD(ENABLED). When not using threading, listening mode stops user firmware from running, so you would not have an opportunity to test the value and calling this always returns false. With Device OS 6.2.0 and later, system thread is always enabled.

setListenTimeout()

Since 0.6.1:

// SYNTAX
Cellular.setListenTimeout(seconds);

Cellular.setListenTimeout(seconds) is used to set a timeout value for Listening Mode. This is rarely needed on cellular devices as cellular devices do not enter listening mode by default.

Since 1.5.0:

You can also specify a value using chrono literals, for example: Cellular.setListenTimeout(5min) for 5 minutes.

getListenTimeout()

Since 0.6.1:

// SYNTAX
uint16_t seconds = Cellular.getListenTimeout();

Cellular.getListenTimeout() is used to get the timeout value currently set for Listening Mode. Values are returned in (uint16_t)seconds, and 0 indicates the timeout is disabled. By default, Cellular devices have a 5 minute timeout set (seconds=300).

lock()

The Cellular object does not have built-in thread-safety. If you want to use things like Cellular.command() from multiple threads, including from a software timer, you must lock and unlock it to prevent data from multiple thread from being interleaved or corrupted.

A call to lock lock() must be balanced with a call to unlock() and not be nested. To make sure every lock is released, it's good practice to use WITH_LOCK like this:

// EXAMPLE USAGE
void loop()
{
  WITH_LOCK(Cellular) {
    Cellular.command("AT\r\n");
  }
}

Never use lock() or WITH_LOCK() within a SINGLE_THREADED_BLOCK() as deadlock can occur.

unlock()

Unlocks the Cellular mutex. See lock().

setCredentials()

Sets 3rd party SIM credentials for the Cellular network from within the user application.

Only a subset of Particle cellular devices are able to use a plastic 4FF nano SIM card from a 3rd-party carrier. This table lists external SIM capability and includes the Electron and Boron only. There are also limits on the number of devices with 3rd-party SIM cards in an account. For more information, see the 3rd-party SIM guide.

Gen 3 Devices (nRF52) (Boron):

SYSTEM_MODE(SEMI_AUTOMATIC);

void setup() {
    // Clears any existing credentials. Use this to restore the use of the Particle SIM.
    Cellular.clearCredentials();

    // You should only use one of the following three commands.
    // Only one set of credentials can be stored.

    // Connects to a cellular network by APN only
    Cellular.setCredentials("broadband");

    // Connects to a cellular network with USERNAME and PASSWORD only
    Cellular.setCredentials("username", "password");

    // Connects to a cellular network with a specified APN, USERNAME and PASSWORD
    Cellular.setCredentials("some-apn", "username", "password");

    Particle.connect();
}

void loop() {
}

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

// SYNTAX
// Connects to a cellular network by APN only
STARTUP(cellular_credentials_set(APN, "", "", NULL));

// Connects to a cellular network with USERNAME and PASSWORD only
STARTUP(cellular_credentials_set("", USERNAME, PASSWORD, NULL));

// Connects to a cellular network with a specified APN, USERNAME and PASSWORD
#include “cellular_hal.h”
STARTUP(cellular_credentials_set(APN, USERNAME, PASSWORD, NULL));

// EXAMPLE - an AT&T APN with no username or password in AUTOMATIC mode

#include "cellular_hal.h"
STARTUP(cellular_credentials_set("broadband", "", "", NULL));

void setup() {
  // your setup code
}

void loop() {
  // your loop code
}

setActiveSim()

Note:

For Boron LTE modules, a special command needs to be given to the cell radio after setting setActiveSim. If this command is not given, the device may end up blinking green, and the device does not connect to cloud. Please refer to this support article if you are switching SIM cards with Boron LTE.

SYSTEM_MODE(SEMI_AUTOMATIC);

void setup() {
    // Choose one of these:
    Cellular.setActiveSim(EXTERNAL_SIM);
    Cellular.setActiveSim(INTERNAL_SIM);
}

void loop() {
}

getActiveSim()

Get the current active SIM (internal or external):

• INTERNAL_SIM = 1
• EXTERNAL_SIM = 2

void setup() {
    Serial.begin();
}

void loop() {
    SimType simType = Cellular.getActiveSim();
    Serial.printlnf("simType=%d", simType);
    delay(5000);
}

getDataUsage()

Note:

A software implementation of Data Usage that pulls sent and received session and total bytes from the cellular modem's internal counters. The sent / received bytes are the gross payload evaluated by the protocol stack, therefore they comprise the TCP and IP header bytes and the packets used to open and close the TCP connection. I.e., these counters account for all overhead in cellular communications.

Note: Cellular.getDataUsage() should only be used for relative measurements on data at runtime. Do not rely upon these figures for absolute and total data usage of your SIM card.

Note: There is a known issue with Sara U260/U270 modem firmware not being able to set/reset the internal counters (which does work on the Sara G350). Because of this limitation, the set/reset function is implemented in software, using the modem's current count as the baseline.

Note: The internal modem counters are typically reset when the modem is power cycled (complete power removal, soft power down or Cellular.off()) or if the PDP context is deactivated and reactivated which can happen asynchronously during runtime. If the Cellular.getDataUsage() API has been read, reset or set, and then the modem's counters are reset for any reason, the next call to Cellular.getDataUsage() for a read will detect that the new reading would be less than the previous reading. When this is detected, the current reading will remain the same, and the now lower modem count will be used as the new baseline. Because of this mechanism, it is generally more accurate to read the getDataUsage() count often. This catches the instances when the modem count is reset, before the count starts to increase again.

Note: LTE Cat M1 devices (SARA-R510S-01B, SARA-R410M-02B), Quectel EG91-E (B-Series SoM B523), Quectel EG-91EX (Tracker SoM T523), and Quectel BG96-MC (TrackerSoM T402) do not support data usage APIs.

To use the data usage API, an instance of the CellularData type needs to be created to read or set counters. All data usage API functions and the CellularData object itself return bool - true indicating the last operation was successful and the CellularData object was updated. For set and get functions, CellularData is passed by reference Cellular.dataUsage(CellularData&); and updated by the function. There are 5 integers and 1 boolean within the CellularData object:

• ok: (bool) a boolean value false when the CellularData object is initially created, and true after the object has been successfully updated by the API. If the last reading failed and the counters were not changed from their previous value, this value is set to false.
• cid: (int) a value from 0-255 that is the index of the current PDP context that the data usage counters are valid for. If this number is -1, the data usage counters have either never been initially set, or the last reading failed and the counters were not changed from their previous value.
• tx_session: (int) number of bytes sent for the current session
• rx_session: (int) number of bytes received for the current session
• tx_total: (int) number of bytes sent total (typical equals the session numbers)
• rx_total: (int) number of bytes received total (typical equals the session numbers)

CellularData is a Printable object, so using it directly with Serial.println(data); will be output as follows:

cid,tx_session,rx_session,tx_total,rx_total
31,1000,300,1000,300

// SYNTAX
// Read Data Usage
CellularData data;
Cellular.getDataUsage(data);

// EXAMPLE

void setup()
{
  Serial.begin(9600);
}

void loop()
{
    if (Serial.available() > 0)
    {
        char c = Serial.read();
        if (c == '1') {
            Serial.println("Read counters of sent or received PSD data!");
            CellularData data;
            if (!Cellular.getDataUsage(data)) {
                Serial.print("Error! Not able to get data.");
            }
            else {
                Serial.printlnf("CID: %d SESSION TX: %d RX: %d TOTAL TX: %d RX: %d",
                    data.cid,
                    data.tx_session, data.rx_session,
                    data.tx_total, data.rx_total);
                Serial.println(data); // Printable
            }
        }
        else if (c == '2') {
            Serial.println("Set all sent/received PSD data counters to 1000!");
            CellularData data;
            data.tx_session = 1000;
            data.rx_session = 1000;
            data.tx_total = 1000;
            data.rx_total = 1000;
            if (!Cellular.setDataUsage(data)) {
                Serial.print("Error! Not able to set data.");
            }
            else {
                Serial.printlnf("CID: %d SESSION TX: %d RX: %d TOTAL TX: %d RX: %d",
                    data.cid,
                    data.tx_session, data.rx_session,
                    data.tx_total, data.rx_total);
                Serial.println(data); // Printable
            }
        }
        else if (c == '3') {
            Serial.println("Reset counter of sent/received PSD data!");
            if (!Cellular.resetDataUsage()) {
                Serial.print("Error! Not able to reset data.");
            }
        }
        else if (c == 'p') {
            Serial.println("Publish some data!");
            Particle.publish("1","a");
        }
        while (Serial.available()) Serial.read(); // Flush the input buffer
    }

}

setDataUsage()

Sets the Data Usage counters to the values indicated in the supplied CellularData object.

Returns bool - true indicating this operation was successful and the CellularData object was updated.

// SYNTAX
// Set Data Usage
CellularData data;
Cellular.setDataUsage(data);

resetDataUsage()

Resets the Data Usage counters to all zero. No CellularData object is required. This is handy to call just before an operation where you'd like to measure data usage.

Returns: bool

• true indicates this operation was successful and the internally stored software offset has been reset to zero. If getDataUsage() was called immediately after without any data being used, the CellularData object would indicate zero data used.

// SYNTAX
// Reset Data Usage
Cellular.resetDataUsage();

RSSI()

Cellular.RSSI() returns an instance of CellularSignal class that allows you to determine signal strength (RSSI) and signal quality of the currently connected Cellular network.

This function queries the cellular modem for the RSSI. This is normally quick, and does not use cellular data.

However, it is possible that the call will still block for an indeterminate amount of time, possibly for as long as 10 minutes. This can occur if the system thread is busy trying to reconnect to cellular and is unable to do so. Doing operations that access the cellular modem or require access to the system thread from a separate worker thread is a good workaround.

CellularSignal Class

This class allows to query a number of signal parameters of the currently connected Cellular network.

getAccessTechnology()

// SYNTAX
CellularSignal sig = Cellular.RSSI();
int rat = sig.getAccessTechnology();

Gets the current radio access technology (RAT) in use.

The following radio technologies are defined:

• NET_ACCESS_TECHNOLOGY_GSM: 2G RAT
• NET_ACCESS_TECHNOLOGY_EDGE: 2G RAT with EDGE
• NET_ACCESS_TECHNOLOGY_UMTS/NET_ACCESS_TECHNOLOGY_UTRAN/NET_ACCESS_TECHNOLOGY_WCDMA: UMTS RAT
• NET_ACCESS_TECHNOLOGY_LTE: LTE RAT
• NET_ACCESS_TECHNOLOGY_LTE_CAT_M1: LTE Cat M1 RAT

getStrength()

Gets the signal strength as a percentage (0.0 - 100.0). See getStrengthValue() on how raw RAT-specific strength values are mapped to 0%-100% range.

// SYNTAX
CellularSignal sig = Cellular.RSSI();
float strength = sig.getStrength();

// EXAMPLE
CellularSignal sig = Cellular.RSSI();
Log.info("Cellular signal strength: %.02f%%", sig.getStrength());

Returns: float

getQuality()

Gets the signal quality as a percentage (0.0 - 100.0). See getQualityValue() on how raw RAT-specific quality values are mapped to 0%-100% range.

// SYNTAX
CellularSignal sig = Cellular.RSSI();
float quality = sig.getQuality();

// EXAMPLE
CellularSignal sig = Cellular.RSSI();
Log.info("Cellular signal quality: %.02f%%", sig.getQuality());

Returns: float

Note: qual is not supported on 2G Electrons (Model G350) and will return 0.

LTE Cat M1 devices (SARA-R410M-02B modem) only return qual with Device OS 1.5.0 and later. Earlier versions returned 0.

getStrengthValue()

// SYNTAX
CellularSignal sig = Cellular.RSSI();
float strength = sig.getStrengthValue();

Gets the raw signal strength value. This value is RAT-specific. See getAccessTechnology() for a list of radio access technologies.

• 2G RAT / 2G RAT with EDGE: RSSI in dBm. Range: [-111, -48] as specified in 3GPP TS 45.008 8.1.4.
• UMTS RAT: RSCP in dBm. Range: [-121, -25] as specified in 3GPP TS 25.133 9.1.1.3.
• LTE Cat M1 RAT: Range: [-141, -44] (dBm)
• LTE Cat 1 RAT: Range: [-141, -44] (dBm)

Returns: float

getQualityValue()

// SYNTAX
CellularSignal sig = Cellular.RSSI();
float quality = sig.getQualityValue();

Gets the raw signal quality value. This value is RAT-specific. See getAccessTechnology() for a list of radio access technologies.

• 2G RAT: Bit Error Rate (BER) in % as specified in 3GPP TS 45.008 8.2.4. Range: [0.14%, 18.10%]
• 2G RAT with EDGE: log10 of Mean Bit Error Probability (BEP) as defined in 3GPP TS 45.008. Range: [-0.60, -3.60] as specified in 3GPP TS 45.008 10.2.3.3.
• UMTS RAT: Ec/Io (dB) [-24.5, 0], as specified in 3GPP TS 25.133 9.1.2.3.
• LTE Cat M1 RAT: Range: [-20, -3] (dB)
• LTE Cat 1 RAT: Range: [-20, -3] (dB)

Returns: float

Note: qual is not supported on 2G Electrons (Model G350) and will return 0.

Before 0.8.0:

Before Device OS 0.8.0, the CellularSignal class only had two member variables, rssi, and qual. These are removed in Device OS 3.0.0 and later and you should use getStrengthValue() and getQualityValue() instead.

// Prior to 0.8.0:
CellularSignal sig = Cellular.RSSI();
Serial.println(sig.rssi);
Serial.println(sig.qual);

getBandAvailable()

Since 0.5.0:

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

Gets the cellular bands currently available in the modem. Bands are the carrier frequencies used to communicate with the cellular network. Some modems have 2 bands available (U260/U270) and others have 4 bands (G350).

To use the band select API, an instance of the CellularBand type needs to be created to read or set bands. All band select API functions and the CellularBand object itself return bool - true indicating the last operation was successful and the CellularBand object was updated. For set and get functions, CellularBand is passed by reference Cellular.getBandSelect(CellularBand&); and updated by the function. There is 1 array, 1 integer, 1 boolean and 1 helper function within the CellularBand object:

• ok: (bool) a boolean value false when the CellularBand object is initially created, and true after the object has been successfully updated by the API. If the last reading failed and the bands were not changed from their previous value, this value is set to false.
• count: (int) a value from 0-5 that is the number of currently selected bands retrieved from the modem after getBandAvailble() or getBandSelect() is called successfully.
• band[5]: (MDM_Band[]) array of up to 5 MDM_Band enumerated types. Available enums are: BAND_DEFAULT, BAND_0, BAND_700, BAND_800, BAND_850, BAND_900, BAND_1500, BAND_1700, BAND_1800, BAND_1900, BAND_2100, BAND_2600. All elements set to 0 when CellularBand object is first created, but after getBandSelect() is called successfully the currently selected bands will be populated started with index 0, i.e., (.band[0]). Can be 5 values when getBandAvailable() is called on a G350 modem, as it will return factory default value of 0 as an available option, i.e., 0,850,900,1800,1900.
• bool isBand(int): helper function built into the CellularBand type that can be used to check if an integer is a valid band. This is helpful if you would like to test a value before manually setting a band in the .band[] array.

CellularBand is a Printable object, so using it directly with Serial.println(CellularBand); will print the number of bands that are retrieved from the modem. This will be output as follows:

// EXAMPLE PRINTABLE
CellularBand band_sel;
// populate band object with fake data
band_sel.band[0] = BAND_850;
band_sel.band[1] = BAND_1900;
band_sel.count = 2;
Log.info(band_sel);

// OUTPUT: band[0],band[1]
850,1900

Here's a full example using all of the functions in the Cellular Band Select API

There is one supported function for getting available bands using the CellularBand object:

bool Cellular.getBandAvailable(CellularBand &band_avail);

Note: getBandAvailable() always sets the first band array element .band[0] as 0 which indicates the first option available is to set the bands back to factory defaults, which includes all bands.

// SYNTAX
CellularBand band_avail;
Cellular.getBandAvailable(band_avail);

// EXAMPLE
CellularBand band_avail;
if (Cellular.getBandSelect(band_avail)) {
    Serial.print("Available bands: ");
    for (int x=0; x<band_avail.count; x++) {
        Serial.printf("%d", band_avail.band[x]);
        if (x+1 < band_avail.count) Serial.printf(",");
    }
    Serial.println();
}
else {
    Serial.printlnf("Bands available not retrieved from the modem!");
}

Cellular global identity

This call returns information about the connected cell tower, including the MCC, MNC, LAC, and Cell Identifier.

The device must be connected to a tower (breathing green or cyan) for this call to be used.

cellular_global_identity function

// PROTOTYPES
cellular_result_t cellular_global_identity(CellularGlobalIdentity* cgi, void* reserved = NULL);

typedef int cellular_result_t;

// EXAMPLE
CellularGlobalIdentity cgi = {0};
cgi.size = sizeof(CellularGlobalIdentity);
cgi.version = CGI_VERSION_LATEST;

cellular_result_t res = cellular_global_identity(&cgi, NULL);
if (res == SYSTEM_ERROR_NONE) {
    Variant tower;
    tower.set("mcc", cgi.mobile_country_code);
    tower.set("mnc", cgi.mobile_network_code);
    tower.set("cid", cgi.cell_id);
    tower.set("lac", cgi.location_area_code);
    // Do something with tower here, like add to a ledger
}

cellular_global_identity result codes

CellularGlobalIdentity structure

// Type definitions
typedef enum __attribute__((__packed__)) CgiVersion
{
    CGI_VERSION_1,
    CGI_VERSION_LATEST = CGI_VERSION_1,
} CgiVersion;

typedef enum __attribute__((__packed__)) CgiFlags
{
    CGI_FLAG_TWO_DIGIT_MNC = 0b00000001, /*!< Indicates two-digit format of Mobile Network Code */
} CgiFlags;

typedef struct __attribute__((__packed__))
{
    uint16_t size; /*!< \c size is specified by the user application, to inform the device-os of the
                      amount of space allocated to the structure */
    uint16_t version;  /*!< \c version is specified by the user application, to inform the
                          device-os of the version of the information to be returned */
    uint8_t reserved;  /*!< \c reserved is allocated for future usage */
    uint8_t cgi_flags; /*!< \c cgi_flags Indicates the structure/configuration of the values in
                           CellularGlobalIdentity */
    uint16_t mobile_country_code; /*!< \c mobile_country_code consists of three decimal digits and
                                     identifies uniquely the country of domicile of the mobile
                                     subscription */
    uint16_t mobile_network_code; /*!< \c mobile_network_code consists of three decimal digits and
                                     identifies the home PLMN of the mobile subscription */
    uint16_t location_area_code;  /*!< \c location_area_code is a fixed length code (of 2 octets)
                                     identifying a location area within a PLMN */
    uint32_t cell_id; /*!< \c cell_id is of fixed length with 4 octets and it can be coded using a
                         full hexadecimal representation */
} CellularGlobalIdentity;

// Example initialization
CellularGlobalIdentity cgi = {0};
cgi.size = sizeof(CellularGlobalIdentity);
cgi.version = CGI_VERSION_LATEST;

getBandSelect()

Since 0.5.0:

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

Gets the cellular bands currently set in the modem. Bands are the carrier frequencies used to communicate with the cellular network.

There is one supported function for getting selected bands using the CellularBand object:

bool Cellular.getBandSelect(CellularBand &band_sel);

// SYNTAX
CellularBand band_sel;
Cellular.getBandSelect(band_sel);

// EXAMPLE
CellularBand band_sel;
if (Cellular.getBandSelect(band_sel)) {
    Serial.print("Selected bands: ");
    for (int x=0; x<band_sel.count; x++) {
        Serial.printf("%d", band_sel.band[x]);
        if (x+1 < band_sel.count) Serial.printf(",");
    }
    Serial.println();
}
else {
    Serial.printlnf("Bands selected not retrieved from the modem!");
}

setBandSelect()

Since 0.5.0:

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

Sets the cellular bands currently set in the modem. Bands are the carrier frequencies used to communicate with the cellular network.

Caution: The Band Select API is an advanced feature designed to give users selective frequency control over their device. When changing location or between cell towers, you may experience connectivity issues if you have only set one specific frequency for use. Because these settings are permanently saved in non-volatile memory, it is recommended to keep the factory default value of including all frequencies with mobile applications. Only use the selective frequency control for stationary applications, or for special use cases.

• Make sure to set the count to the appropriate number of bands set in the CellularBand object before calling setBandSelect().
• Use the .isBand(int) helper function to determine if an integer value is a valid band. It still may not be valid for the particular modem you are using, in which case setBandSelect() will return false and .ok will also be set to false.
• When trying to set bands that are already set, they will not be written to Non-Volatile Memory (NVM) again.
• When updating the bands in the modem, they will be saved to NVM and will be remain as set when the modem power cycles.
• Setting .band[0] to BAND_0 or BAND_DEFAULT and .count to 1 will restore factory defaults.

There are two supported functions for setting bands, one uses the CellularBand object, and the second allow you to pass in a comma delimited string of bands:

bool Cellular.setBandSelect(const char* band_set);

bool Cellular.setBandSelect(CellularBand &band_set);

// SYNTAX
CellularBand band_set;
Cellular.setBandSelect(band_set);

// or

Cellular.setBandSelect("850,1900"); // set two bands
Cellular.setBandSelect("0"); // factory defaults

// EXAMPLE
Serial.println("Setting bands to 850 only");
CellularBand band_set;
band_set.band[0] = BAND_850;
band_set.band[1] = BAND_1900;
band_set.count = 2;
if (Cellular.setBandSelect(band_set)) {
    Serial.print(band_set);
    Serial.println(" band(s) set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.print(band_set);
    Serial.println(" band(s) not valid! Use getBandAvailable() to query for valid bands.");
}

// EXAMPLE
Serial.println("Restoring factory defaults with the CellularBand object");
CellularBand band_set;
band_set.band[0] = BAND_DEFAULT;
band_set.count = 1;
if (Cellular.setBandSelect(band_set)) {
    Serial.println("Factory defaults set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.println("Restoring factory defaults failed!");
}

// EXAMPLE
Serial.println("Restoring factory defaults with strings");
if (Cellular.setBandSelect("0")) {
    Serial.println("Factory defaults set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.println("Restoring factory defaults failed!");
}

resolve()

Since 0.6.1:

Cellular.resolve() finds the IP address for a domain name.

// SYNTAX
IPAddress ip = Cellular.resolve(name);

Parameters:

• name: the domain name to resolve (string)

It returns the IP address if the domain name is found, otherwise a blank IP address.

// EXAMPLE USAGE

IPAddress ip;
void setup() {
   ip = Cellular.resolve("www.google.com");
   if(ip) {
     // IP address was resolved
   } else {
     // name resolution failed
   }
}

localIP()

Since 0.5.0:

Cellular.localIP() returns the local (private) IP address assigned to the device as an IPAddress.

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
  // Prints out the local (private) IP over Serial
  Log.info("localIP: %s", Cellular.localIP().toString().c_str());
}

command()

Cellular.command() is a powerful API that allows users access to directly send AT commands to, and parse responses returned from, the Cellular module. Commands may be sent with and without printf style formatting. The API also includes the ability pass a callback function pointer which is used to parse the response returned from the cellular module.

Since 0.9.0: On the Boron, Cellular.command requires Device OS 0.9.0 or later.

Note: Obviously for this command to work the cellular module needs to be switched on, which is not automatically the case in SYSTEM_MODE(MANUAL) or SYSTEM_MODE(SEMI_AUTOMATIC). This can be achieved explicitly via Cellular.on() or implicitly by calling Cellular.connect() or Particle.connect().

References:

• u-blox AT command reference (BRN314, BRN310, E310, E270, E260, G350)
• u-blox R410 AT command reference (B404, B402, BRN404, BRN402, E404, E402, ELC404, ELC402, LTE Cat M1)
• u-blox R510 AT command reference (BRN404X, B404X LTE Cat M1)
• u-blox AT command examples application note
• Quectel EG91 AT command reference (T524, T523)
• Quectel BG96 AT command reference (T404, T402)

The prototype definition is as follows:

int Cellular.command(_CALLBACKPTR_MDM cb, void* param, system_tick_t timeout, const char* format, ...);

Cellular.command() takes one or more arguments in 4 basic types of signatures.

// SYNTAX (4 basic signatures with/without printf style formatting)
int ret = Cellular.command(cb, param, timeout, format, ...);
int ret = Cellular.command(cb, param, timeout, format);
int ret = Cellular.command(cb, param, format, ...);
int ret = Cellular.command(cb, param, format);
int ret = Cellular.command(timeout, format, ...);
int ret = Cellular.command(timeout, format);
int ret = Cellular.command(format, ...)
int ret = Cellular.command(format);

• cb: callback function pointer to a user specified function that parses the results of the AT command response.
• param: (void*) a pointer to the variable that will be updated by the callback function.
• timeout: (system_tick_t) the timeout value specified in milliseconds (default is 10000 milliseconds).
• format: (const char*) contains your AT command and any desired format specifiers, followed by \r\n.
• ...: additional arguments optionally required as input to their respective format string format specifiers.

Cellular.command() returns an int with one of the following 6 enumerated AT command responses:

• NOT_FOUND = 0
• WAIT = -1 // TIMEOUT
• RESP_OK = -2
• RESP_ERROR = -3
• RESP_PROMPT = -4
• RESP_ABORTED = -5

// EXAMPLE - Get the ICCID number of the inserted SIM card
SerialLogHandler logHandler;

int callbackICCID(int type, const char* buf, int len, char* iccid)
{
  if ((type == TYPE_PLUS) && iccid) {
    if (sscanf(buf, "\r\n+CCID: %[^\r]\r\n", iccid) == 1)
      /*nothing*/;
  }
  return WAIT;
}

void setup()
{
  char iccid[32] = "";
  if ((RESP_OK == Cellular.command(callbackICCID, iccid, 10000, "AT+CCID\r\n"))
    && (strcmp(iccid,"") != 0))
  {
    Log.info("SIM ICCID = %s\r\n", iccid);
  }
  else
  {
    Log.info("SIM ICCID NOT FOUND!");
  }
}

void loop()
{
  // your loop code
}

The cb function prototype is defined as:

int callback(int type, const char* buf, int len, void* param);

The four Cellular.command() callback arguments are defined as follows:

• type: (int) one of 13 different enumerated AT command response types.
• buf: (const char*) a pointer to the character array containing the AT command response.
• len: (int) length of the AT command response buf.
• param: (void*) a pointer to the variable or structure being updated by the callback function.
• returns an int - user specified callback return value, default is return WAIT; which keeps the system invoking the callback again as more of the AT command response is received. Optionally any one of the 6 enumerated AT command responses previously described can be used as a return type which will force the Cellular.command() to return the same value. AT commands typically end with an OK response, so even after a response is parsed, it is recommended to wait for the final OK response to be parsed and returned by the system. Then after testing if(Cellular.command() == RESP_OK) and any other optional qualifiers, should you act upon the results contained in the variable/structure passed into the callback.

There are 13 different enumerated AT command responses passed by the system into the Cellular.command() callback as type. These are used to help qualify which type of response has already been parsed by the system.

• TYPE_UNKNOWN = 0x000000
• TYPE_OK = 0x110000
• TYPE_ERROR = 0x120000
• TYPE_RING = 0x210000
• TYPE_CONNECT = 0x220000
• TYPE_NOCARRIER = 0x230000
• TYPE_NODIALTONE = 0x240000
• TYPE_BUSY = 0x250000
• TYPE_NOANSWER = 0x260000
• TYPE_PROMPT = 0x300000
• TYPE_PLUS = 0x400000
• TYPE_TEXT = 0x500000
• TYPE_ABORTED = 0x600000

It is possible that the call will block for an indeterminate amount of time, possibly for as long as 10 minutes. This can occur if the system thread is busy trying to reconnect to cellular and is unable to do so. Doing operations that access the cellular modem or require access to the system thread from a separate worker thread is a good workaround.

Battery voltage

Battery Voltage - Photon 2

The Photon 2 does not have a fuel gauge chip, however you can determine the voltage of the LiPo battery, if present. The P2 does not include a LiPo battery connector, but if you connect your battery to VBAT_MEAS, this technique also works with the P2.

float voltage = analogRead(A6) / 819.2;

The constant is from the ADC range (0 - 4095) mapped to the voltage from 0 - 5 VDC (the maximum supported on VBAT_MEAS).

There is a CHG pin defined on the P2, however it does not work properly.

Show older information about CHG

pinMode(CHG, INPUT_PULLUP);
bool charging = digitalRead(CHG);

Battery Voltage - Argon

The Argon device does not have a fuel gauge chip, however you can determine the voltage of the LiPo battery, if present.

float voltage = analogRead(BATT) * 0.0011224;

The constant 0.0011224 is based on the voltage divider circuit (R1 = 806K, R2 = 2M) that lowers the 3.6V LiPo battery output to a value that can be read by the ADC.

The charge indicator on the Argon can be read using:

bool charging = !digitalRead(CHG);

In other words, the CHG input is 0 when charging and 1 when not charging, and the ! inverts this logic to make it easier to use.

On the Argon, the PWR input is 1 when there is 5V power on the Micro USB connector or VUSB pin. You can use digitalRead(PWR) to find the value. On cellular devices with a PMIC, you should use System.powerSource() instead.

Note:

FuelGauge

The on-board Fuel Gauge allows you to monitor the battery voltage, state of charge and set low voltage battery thresholds. Use an instance of the FuelGauge library to call the various fuel gauge functions.

// EXAMPLE
FuelGauge fuel;

Note:

getVCell()

// PROTOTYPE
float getVCell();

// EXAMPLE
FuelGauge fuel;
Log.info( "voltage=%.2f", fuel.getVCell() );

Returns the battery voltage as a float. Returns -1.0 if the fuel gauge cannot be read.

getSoC()

// PROTOTYPE
float getSoC(); 

// EXAMPLE
FuelGauge fuel;
Log.info( "SoC=%.2f", fuel.getSoC() );

Returns the State of Charge in percentage from 0-100% as a float. Returns -1.0 if the fuel gauge cannot be read.

Note that in most cases, "fully charged" state (red charging LED goes off) will result in a SoC of 80%, not 100%. Using getNormalizedSoC() normalizes the value based on the charge voltage so the SoC will be 100% when the charge LED goes off.

In some cases you can increase the charge voltage to get a higher SoC, but there are limits, based on temperature.

Since 1.5.0:

It may be preferable to use System.batteryCharge() instead of using getSoC(), which uses the value in device diagnostics, which eventually uses getNormalizedSoC().

getNormalizedSoC()

// PROTOTYPE
float getNormalizedSoC()

Returns the State of Charge in percentage from 0-100% as a float, normalized based on the charge voltage. Returns -1.0 if the fuel gauge cannot be read.

It may be easier to use System.batteryCharge() instead of using getNormalizedSoC() directly. System.batteryCharge() uses the value in device diagnostics, which eventually uses getNormalizedSoC().

getVersion()

int getVersion();

getCompensateValue()

byte getCompensateValue();

getAlertThreshold()

byte getAlertThreshold();

setAlertThreshold()

void setAlertThreshold(byte threshold);

getAlert()

boolean getAlert();

clearAlert()

void clearAlert();

reset()

void reset();

quickStart()

void quickStart();

sleep()

void sleep();

wakeup()

void wakeup();

Input/Output

Additional information on which pins can be used for which functions is available on the pin information page.

Gen 3 Devices (nRF52) (Tracker SoM, Tracker One):

P2 and Photon 2 Devices (RTL872x):

pinMode()

pinMode() configures the specified pin to behave either as an input (with or without an internal weak pull-up or pull-down resistor), or an output.

// PROTOTYPE
void pinMode(uint16_t pin, PinMode mode)

// EXAMPLE USAGE
int button = D0;                      // button is connected to D0
int LED = D1;                         // LED is connected to D1

void setup()
{
  pinMode(LED, OUTPUT);               // sets pin as output
  pinMode(button, INPUT_PULLDOWN);    // sets pin as input
}

void loop()
{
  // blink the LED as long as the button is pressed
  while(digitalRead(button) == HIGH) {
    digitalWrite(LED, HIGH);          // sets the LED on
    delay(200);                       // waits for 200mS
    digitalWrite(LED, LOW);           // sets the LED off
    delay(200);                       // waits for 200mS
  }
}

pinMode() takes two arguments:

• pin: the pin you want to set the mode of (A0, A1, D0, D1, TX, RX, etc.). The type pin_t can be used instead of uint16_t to make it more obvious that the code accepts a pin number in your code.

• mode: the mode to set to pin to:

  • INPUT digital input (the default at power-up)
  • INPUT_PULLUP digital input with a pull-up resistor to 3V3
  • INPUT_PULLDOWN digital input with a pull-down to GND
  • OUTPUT an output (push-pull)
  • OUTPUT_OPEN_DRAIN an open-drain or open-collector output. HIGH (1) leaves the output in high impedance state, LOW (0) pulls the output low. Typically used with an external pull-up resistor to allow any of multiple devices to set the value low safely.

You do not need to set the pinMode() to read an analog value using analogRead as the pin will automatically be set to the correct mode when analogRead is called.

When porting code from Arudino, pin numbers are numbered (0, 1, 2, ...) in Arduino code. Pin D0 has a value of 0, but it's best to use Particle pin names like D0 instead of just 0. This is especially true as the numeric value of A0 varies depending on the device and how many digital pins it has. For example, on the Argon, A0 is 19 but on the Photon it's 10.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

void disable()
{
    SystemPowerConfiguration conf;
    conf.feature(SystemPowerFeature::DISABLE);
    System.setPowerConfiguration(conf);
}
STARTUP(disable());

P2 and Photon 2 Devices (RTL872x):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

getPinMode(pin)

Retrieves the current pin mode.

// PROTOTYPE
PinMode getPinMode(uint16_t pin)

// EXAMPLE

if (getPinMode(D0)==INPUT) {
  // D0 is an input pin
}

digitalWrite()

Write a HIGH or a LOW value to a GPIO pin.

// PROTOTYPE
void digitalWrite(uint16_t pin, uint8_t value)

If the pin has been configured as an OUTPUT with pinMode() or if previously used with analogWrite(), its voltage will be set to the corresponding value: 3.3V for HIGH, 0V (ground) for LOW.

digitalWrite() takes two arguments, pin: the number of the pin whose value you wish to set and value: HIGH or LOW.

digitalWrite() does not return anything.

// EXAMPLE USAGE
int LED = D1;              // LED connected to D1

void setup()
{
  pinMode(LED, OUTPUT);    // sets pin as output
}

void loop()
{
  digitalWrite(LED, HIGH); // sets the LED on
  delay(200);              // waits for 200mS
  digitalWrite(LED, LOW);  // sets the LED off
  delay(200);              // waits for 200mS
}

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

digitalRead()

Reads the value from a specified digital pin, either HIGH or LOW.

// PROTOTYPE
int32_t digitalRead(uint16_t pin)

digitalRead() takes one argument, pin: the number of the digital pin you want to read.

digitalRead() returns HIGH or LOW.

// EXAMPLE USAGE
int button = D0;                   // button is connected to D0
int LED = D1;                      // LED is connected to D1
int val = 0;                       // variable to store the read value

void setup()
{
  pinMode(LED, OUTPUT);            // sets pin as output
  pinMode(button, INPUT_PULLDOWN); // sets pin as input
}

void loop()
{
  val = digitalRead(button);       // read the input pin
  digitalWrite(LED, val);          // sets the LED to the button's value
}

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

P2 and Photon 2 Devices (RTL872x):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

pinSetDriveStrength()

Since 2.0.0:

// PROTOTYPE
int pinSetDriveStrength(pin_t pin, DriveStrength drive);

Sets the pin drive strength on Gen 3 devices with Device OS 2.0.0 and later, or P2/Photon 2 (RTL872x) with Device OS 5.5.0 and later.

DriveStrength is one of:

• DriveStrength::DEFAULT (STANDARD)
• DriveStrength::STANDARD
• DriveStrength::HIGH

Returns SYSTEM_ERROR_NONE (0) on success, or a non-zero system error code on error.

The drive strength is typically 2 mA in standard drive mode (the default), and 9 mA in high drive mode.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

analogWrite() (PWM)

Writes an analog value to a pin as a digital PWM (pulse-width modulated) signal. The default frequency of the PWM signal is 500 Hz.

Can be used to light a LED at varying brightnesses or drive a motor at various speeds. After a call to analogWrite(), the pin will generate a steady square wave of the specified duty cycle until the next call to analogWrite() (or a call to digitalRead() or digitalWrite() on the same pin).

// SYNTAX
analogWrite(pin, value);
analogWrite(pin, value, frequency);

analogWrite() takes two or three arguments:

• pin: the number of the pin whose value you wish to set
• value: the duty cycle: between 0 (always off) and 255 (always on). Since 0.6.0: between 0 and 255 (default 8-bit resolution) or 2^(analogWriteResolution(pin)) - 1 in general.
• frequency: the PWM frequency (optional). If not specified, the default is 500 Hz.

NOTE: pinMode(pin, OUTPUT); is required before calling analogWrite(pin, value); or else the pin will not be initialized as a PWM output and set to the desired duty cycle.

analogWrite() does not return anything.

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

// EXAMPLE USAGE

int ledPin = D1;               // LED connected to digital pin D1
int analogPin = A0;            // potentiometer connected to analog pin A0
int val = 0;                   // variable to store the read value

void setup()
{
  pinMode(ledPin, OUTPUT);     // sets the pin as output
}

void loop()
{
  val = analogRead(analogPin); // read the input pin
  analogWrite(ledPin, val/16); // analogRead values go from 0 to 4095,
                               // analogWrite values from 0 to 255.
  delay(10);
}

NOTE: When used with PWM capable pins, the analogWrite() function sets up these pins as PWM only.

Additional information on which pins can be used for PWM output is available on the pin information page.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

analogWriteResolution() (PWM)

Since 0.6.0:

Sets or retrieves the resolution of analogWrite() function of a particular pin.

analogWriteResolution() takes one or two arguments:

• pin: the number of the pin whose resolution you wish to set or retrieve
• resolution: (optional) resolution in bits. The value can range from 2 to 31 bits. If the resolution is not supported, it will not be applied. The default is 8.

analogWriteResolution() returns currently set resolution.

// EXAMPLE USAGE
pinMode(D1, OUTPUT);     // sets the pin as output
analogWriteResolution(D1, 12); // sets analogWrite resolution to 12 bits
analogWrite(D1, 3000, 1000); // 3000/4095 = ~73% duty cycle at 1kHz

NOTE: The resolution also affects maximum frequency that can be used with analogWrite(). The maximum frequency allowed with current resolution can be checked by calling analogWriteMaxFrequency().

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

analogWriteMaxFrequency() (PWM)

Since 0.6.0:

Returns maximum frequency that can be used with analogWrite() on this pin.

analogWriteMaxFrequency() takes one argument:

• pin: the number of the pin

// EXAMPLE USAGE
pinMode(D1, OUTPUT);     // sets the pin as output
analogWriteResolution(D1, 12); // sets analogWrite resolution to 12 bits
int maxFreq = analogWriteMaxFrequency(D1);
analogWrite(D1, 3000, maxFreq / 2); // 3000/4095 = ~73% duty cycle

Analog Output (DAC)

The Photon, P1, Electron, and E-Series support true analog output on pins DAC (DAC1 or A6 in code) and A3 (DAC2 or A3 in code). Using analogWrite(pin, value) with these pins, the output of the pin is set to an analog voltage from 0V to 3.3V that corresponds to values from 0-4095.

NOTE: This output is buffered inside the STM32 to allow for more output current at the cost of not being able to achieve rail-to-rail performance, i.e., the output will be about 50mV when the DAC is set to 0, and approx 50mV less than the 3V3 voltage when DAC output is set to 4095.

NOTE: Device OS version 0.4.6 and 0.4.7 only - not applicable to versions from 0.4.9 onwards: While for PWM pins one single call to pinMode(pin, OUTPUT); sets the pin mode for multiple analogWrite(pin, value); calls, for DAC pins you need to set pinMode(DAC, OUTPUT); each time you want to perform an analogWrite().

// SYNTAX
pinMode(DAC1, OUTPUT);
analogWrite(DAC1, 1024);
// sets DAC pin to an output voltage of 1024/4095 * 3.3V = 0.825V.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

analogRead() (ADC)

// SYNTAX
analogRead(pin);

// EXAMPLE USAGE
int ledPin = D1;                // LED connected to digital pin D1
int analogPin = A0;             // potentiometer connected to analog pin A0
int val = 0;                    // variable to store the read value

void setup()
{
  // Note: analogPin pin does not require pinMode()

  pinMode(ledPin, OUTPUT);      // sets the ledPin as output
}

void loop()
{
  val = analogRead(analogPin);  // read the analogPin
  analogWrite(ledPin, val/16);  // analogRead values go from 0 to 4095, analogWrite values from 0 to 255
  delay(10);
}

Reads the value from the specified analog pin.

analogRead() takes one argument pin: the number of the analog input pin to read from, such as A0 or A1.

analogRead() returns an integer value ranging from 0 to 4095 (12-bit).

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

P2 and Photon 2 Devices (RTL872x):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

setADCSampleTime()

The function setADCSampleTime(duration) is used to change the default sample time for analogRead().

On the Photon, P1, Electron, and E-Series this parameter can be one of the following values (ADC clock = 30MHz or 33.3ns per cycle):

• ADC_SampleTime_3Cycles: Sample time equal to 3 cycles, 100ns
• ADC_SampleTime_15Cycles: Sample time equal to 15 cycles, 500ns
• ADC_SampleTime_28Cycles: Sample time equal to 28 cycles, 933ns
• ADC_SampleTime_56Cycles: Sample time equal to 56 cycles, 1.87us
• ADC_SampleTime_84Cycles: Sample time equal to 84 cycles, 2.80us
• ADC_SampleTime_112Cycles: Sample time equal to 112 cycles, 3.73us
• ADC_SampleTime_144Cycles: Sample time equal to 144 cycles, 4.80us
• ADC_SampleTime_480Cycles: Sample time equal to 480 cycles, 16.0us (default)

The default is ADC_SampleTime_480Cycles. This means that the ADC is sampled for 16 us which can provide a more accurate reading, at the expense of taking longer than using a shorter ADC sample time. If you are measuring a high frequency signal, such as audio, you will almost certainly want to reduce the ADC sample time.

Furthermore, 5 consecutive samples at the sample time are averaged in analogRead(), so the time to convert is closer to 80 us, not 16 us, at 480 cycles.

Note:

analogSetReference

Since 4.1.0:

This feature is only present in 4.1.0 and later on the 4.x LTS branch, and in 5.3.0 and later in the 5.x developer prevent branch.

Set the ADC input reference. This does not affect the range of the ADC, which is always 0 - 3.3V with a 12-bit range (0 - 4095).

On nRF52840 devices, this call determines whether the ADC voltage reference is VCC (3V3), or the MCU internal voltage reference. On most devices, the default is AdcReference::VCC (3V3). The exception is the Boron 404X, which defaults to AdcReference::INTERNAL.

On RTL872x devices (P2, Photon 2), the ADC reference is always AdcReference::INTERNAL and attempting to set it will return SYSTEM_ERROR_NOT_SUPPORTED.

Returns 0 on success, or a non-zero system error code.

// PROTOTYPE
int analogSetReference(AdcReference reference);

// EXAPLE
analogSetReference(AdcReference::INTERNAL)

The valid values for analogSetReference are:

• AdcReference::DEFAULT Use the default value for this device
• AdcReference::INTERNAL Use the MCU internal voltage reference if supported by the device
• AdcReference::VCC Use VCC (3V3) as the voltage reference if supported by the device

analogGetReference

Since 4.1.0:

This feature is only present in 4.1.0 and later on the 4.x LTS branch, and in 5.3.0 and later in the 5.x developer prevent branch.

Gets the ADC reference voltage.

Returns:

• AdcReference::INTERNAL
• AdcReference::VCC

Note that if set to DEFAULT, the actual reference is returned, not AdcReference::DEFAULT.

// PROTOTYPE
AdcReference analogGetReference(void);

// EXAPLE
if (analogGetReference() == AdcReference::INTERNAL) {
  // Do something
}

Low level input/output

The Input/Ouput functions include safety checks such as making sure a pin is set to OUTPUT when doing a digitalWrite() or that the pin is not being used for a timer function. These safety measures represent good coding and system design practice.

There are times when the fastest possible input/output operations are crucial to an applications performance. The SPI, UART (Serial) or I2C hardware are examples of low level performance-oriented devices. There are, however, times when these devices may not be suitable or available. For example, One-wire support is done in software, not hardware.

In order to provide the fastest possible bit-oriented I/O, the normal safety checks must be skipped. As such, please be aware that the programmer is responsible for proper planning and use of the low level I/O functions.

Prior to using the following low-level functions, pinMode() must be used to configure the target pin.

pinSetFast()

Write a HIGH value to a digital pin.

// SYNTAX
pinSetFast(pin);

pinSetFast() takes one argument, pin: the number of the pin whose value you wish to set HIGH.

pinSetFast() does not return anything.

// EXAMPLE USAGE
int LED = D7;              // LED connected to D7

void setup()
{
  pinMode(LED, OUTPUT);    // sets pin as output
}

void loop()
{
  pinSetFast(LED);           // set the LED on
  delay(500);
  pinResetFast(LED);       // set the LED off
  delay(500);
}

pinResetFast()

Write a LOW value to a digital pin.

// SYNTAX
pinResetFast(pin);

pinResetFast() takes one argument, pin: the number of the pin whose value you wish to set LOW.

pinResetFast() does not return anything.

// EXAMPLE USAGE
int LED = D7;              // LED connected to D7

void setup()
{
  pinMode(LED, OUTPUT);    // sets pin as output
}

void loop()
{
  pinSetFast(LED);           // set the LED on
  delay(500);
  pinResetFast(LED);       // set the LED off
  delay(500);
}

digitalWriteFast()

Write a HIGH or LOW value to a digital pin. This function will call pinSetFast() or pinResetFast() based on value and is useful when value is calculated. As such, this imposes a slight time overhead.

// SYNTAX
digitalWriteFast(pin, value);

digitalWriteFast() pin: the number of the pin whose value you wish to set and value: HIGH or LOW.

digitalWriteFast() does not return anything.

// EXAMPLE USAGE
int LED = D7;              // LED connected to D7

void setup()
{
  pinMode(LED, OUTPUT);    // sets pin as output
}

void loop()
{
  digitalWriteFast(LED, HIGH);           // set the LED on
  delay(500);
  digitalWriteFast(LED, LOW);          // set the LED off
  delay(500);
}

pinReadFast()

Reads the value from a specified digital pin, either HIGH or LOW.

// SYNTAX
pinReadFast(pin);

pinReadFast() takes one argument, pin: the number of the digital pin you want to read.

pinReadFast() returns HIGH or LOW.

// EXAMPLE USAGE
int button = D0;                   // button is connected to D0
int LED = D1;                      // LED is connected to D1
int val = 0;                       // variable to store the read value

void setup()
{
  pinMode(LED, OUTPUT);            // sets pin as output
  pinMode(button, INPUT_PULLDOWN); // sets pin as input
}

void loop()
{
  val = pinReadFast(button);       // read the input pin
  digitalWriteFast(LED, val);      // sets the LED to the button's value
}

Input/Output - Advanced

tone()

Generates a square wave of the specified frequency and duration (and 50% duty cycle) on a timer channel pin which supports PWM. Use of the tone() function will interfere with PWM output on the selected pin. tone() is generally used to make sounds or music on speakers or piezo buzzers.

// SYNTAX
tone(pin, frequency, duration)

tone() takes three arguments, pin: the pin on which to generate the tone, frequency: the frequency of the tone in hertz and duration: the duration of the tone in milliseconds (a zero value = continuous tone).

The frequency range is from 20Hz to 20kHz. Frequencies outside this range will not be played.

tone() does not return anything.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

Additional information on which pins can be used for tone() is available on the pin information page.

#include "application.h"
// The Photon has 9 PWM pins: D0, D1, D2, D3, A4, A5, A7, RX and TX.
//
// EXAMPLE USAGE
// Plays a melody - Connect small speaker to speakerPin
int speakerPin = D0;

// Notes defined in microseconds (Period/2) 
// from note C to B, Octaves 3 through 7
int notes[] = 
{0,
/* C,  C#,   D,  D#,   E,   F,  F#,   G,  G#,   A,  A#,   B */
3817,3597,3401,3205,3030,2857,2703,2551,2404,2273,2146,2024,   // 3 (1-12)
1908,1805,1701,1608,1515,1433,1351,1276,1205,1136,1073,1012,   // 4 (13-24)
 956, 903, 852, 804, 759, 716, 676, 638, 602, 568, 536, 506,   // 5 (25-37)
 478, 451, 426, 402, 379, 358, 338, 319, 301, 284, 268, 253,   // 6 (38-50)
 239, 226, 213, 201, 190, 179, 169, 159, 151, 142, 134, 127 }; // 7 (51-62)

#define NOTE_G3  2551
#define NOTE_G4  1276
#define NOTE_C5  956
#define NOTE_E5  759
#define NOTE_G5  638
#define RELEASE  20
#define BPM      100

// notes in the melody:
int melody[] = {NOTE_E5,NOTE_E5,0,NOTE_E5,0,NOTE_C5,NOTE_E5,0,NOTE_G5,0,0,NOTE_G4};

// note durations: 4 = quarter note, 2 = half note, etc.:
int noteDurations[] = {4,4,4,4,4,4,4,4,4,2,4,4};

void setup() {
  // iterate over the notes of the melody:
  for (int thisNote = 0; thisNote < 12; thisNote++) {

    // to calculate the note duration, take one second
    // divided by the note type.
    // e.g. quarter note = 1000 / 4, eighth note = 1000/8, etc.
    int noteDuration = 60*1000/BPM/noteDurations[thisNote];
    tone(speakerPin, (melody[thisNote]!=0)?(500000/melody[thisNote]):0,noteDuration-RELEASE);

    // blocking delay needed because tone() does not block
    delay(noteDuration);
  }
}

noTone()

Stops the generation of a square wave triggered by tone() on a specified pin. Has no effect if no tone is being generated.

The available pins are the same as for tone().

// SYNTAX
noTone(pin)

noTone() takes one argument, pin: the pin on which to stop generating the tone.

noTone() does not return anything.

//See the tone() example

shiftOut()

Shifts out a byte of data one bit at a time on a specified pin. Starts from either the most (i.e. the leftmost) or least (rightmost) significant bit. Each bit is written in turn to a data pin, after which a clock pin is pulsed (taken high, then low) to indicate that the bit is available.

NOTE: if you're interfacing with a device that's clocked by rising edges, you'll need to make sure that the clock pin is low before the call to shiftOut(), e.g. with a call to digitalWrite(clockPin, LOW).

This is a software implementation; see also the SPI function, which provides a hardware implementation that is faster but works only on specific pins.

// SYNTAX
shiftOut(dataPin, clockPin, bitOrder, value)

// EXAMPLE USAGE

// Use digital pins D0 for data and D1 for clock
int dataPin = D0;
int clock = D1;

uint8_t data = 50;

setup() {
    // Set data and clock pins as OUTPUT pins before using shiftOut()
    pinMode(dataPin, OUTPUT);
    pinMode(clock, OUTPUT);

    // shift out data using MSB first
    shiftOut(dataPin, clock, MSBFIRST, data);

    // Or do this for LSBFIRST serial
    shiftOut(dataPin, clock, LSBFIRST, data);
}

loop() {
    // nothing to do
}

shiftOut() takes four arguments, 'dataPin': the pin on which to output each bit, clockPin: the pin to toggle once the dataPin has been set to the correct value, bitOrder: which order to shift out the bits; either MSBFIRST or LSBFIRST (Most Significant Bit First, or, Least Significant Bit First) and value: the data (byte) to shift out.

shiftOut() does not return anything.

shiftIn()

Shifts in a byte of data one bit at a time. Starts from either the most (i.e. the leftmost) or least (rightmost) significant bit. For each bit, the clock pin is pulled high, the next bit is read from the data line, and then the clock pin is taken low.

NOTE: if you're interfacing with a device that's clocked by rising edges, you'll need to make sure that the clock pin is low before the call to shiftOut(), e.g. with a call to digitalWrite(clockPin, LOW).

This is a software implementation; see also the SPI function, which provides a hardware implementation that is faster but works only on specific pins.

// SYNTAX
shiftIn(dataPin, clockPin, bitOrder)

// EXAMPLE USAGE

// Use digital pins D0 for data and D1 for clock
int dataPin = D0;
int clock = D1;

uint8_t data;

setup() {
    // Set data as INPUT and clock pin as OUTPUT before using shiftIn()
    pinMode(dataPin, INPUT);
    pinMode(clock, OUTPUT);

    // shift in data using MSB first
    data = shiftIn(dataPin, clock, MSBFIRST);

    // Or do this for LSBFIRST serial
    data = shiftIn(dataPin, clock, LSBFIRST);
}

loop() {
    // nothing to do
}

shiftIn() takes three arguments, 'dataPin': the pin on which to input each bit, clockPin: the pin to toggle to signal a read from dataPin, bitOrder: which order to shift in the bits; either MSBFIRST or LSBFIRST (Most Significant Bit First, or, Least Significant Bit First).

shiftIn() returns the byte value read.

pulseIn()

Since 0.4.7:

Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, pulseIn() waits for the pin to go HIGH, starts timing, then waits for the pin to go LOW and stops timing. Returns the length of the pulse in microseconds or 0 if no complete pulse was received within the timeout.

The timing of this function is based on an internal hardware counter derived from the system tick clock. Resolution is 1/120MHz for Photon/P1/Electron). Works on pulses from 10 microseconds to 3 seconds in length. Please note that if the pin is already reading the desired value when the function is called, it will wait for the pin to be the opposite state of the desired value, and then finally measure the duration of the desired value. This routine is blocking and does not use interrupts. The pulseIn() routine will time out and return 0 after 3 seconds.

// SYNTAX
pulseIn(pin, value)

pulseIn() takes two arguments, pin: the pin on which you want to read the pulse (this can be any GPIO, e.g. D1, A2, C0, B3, etc..), value: type of pulse to read: either HIGH or LOW. pin should be set to one of three pinMode()'s prior to using pulseIn(), INPUT, INPUT_PULLUP or INPUT_PULLDOWN.

pulseIn() returns the length of the pulse (in microseconds) or 0 if no pulse is completed before the 3 second timeout (unsigned long)

// EXAMPLE
SerialLogHandler logHandler;

unsigned long duration;

void setup()
{
    Serial.begin(9600);
    pinMode(D0, INPUT);

    // Pulse generator, connect D1 to D0 with a jumper
    // PWM output is 500Hz at 50% duty cycle
    // 1000us HIGH, 1000us LOW
    pinMode(D1, OUTPUT);
    analogWrite(D1, 128);
}

void loop()
{
    duration = pulseIn(D0, HIGH);
    Log.info("%d us", duration);
    delay(1000);
}

/* OUTPUT
 * 1003 us
 * 1003 us
 * 1003 us
 * 1003 us
 */

Power manager

The Power Manager API provides a way to set PMIC (Power Management IC) settings such as input volage, input current limit, charge current, and charge termination voltage using a simple API. The Power Manager settings are persistent and saved in configuration flash so you can set them once and they will continue to be used.

To set the Power Manager configuration, create a SystemPowerConfiguration object and use the methods below to adjust the settings:

Note:

powerSourceMaxCurrent - SystemPowerConfiguration

Set maximum current the power source can provide. This applies only when powered through VIN. When powering by USB, the maximum current is negotiated with your computer or power adapter automatically.

The valid values are: 100, 150, 500, 900, 1200 or 1500 (mA). While the bq24195 PMIC has settings for 2000 and 3000, these will still be limited to around 1590 mA because the input current is limited to the lower of the powerSourceMaxCurrent and the hardware ILIM resistors, which are set to around 1500 mA.

When powering by a USB power adapter that implements DPDM (USB current limit discovery), the lower of that value, powerSourceMaxCurrent, and ILIM resistors will be used.

The default is 900 mA.

// PROTOTYPES
SystemPowerConfiguration& powerSourceMinVoltage(uint16_t voltage)
uint16_t powerSourceMinVoltage() 

powerSourceMinVoltage

Set minimum voltage required for VIN to be used. This applies only when powered through VIN. The value is in millivolts or 1000ths of a volt, so 3880 is 3.880 volts.

The default is 3880 (3.88 volts).

// PROTOTYPES
SystemPowerConfiguration& powerSourceMinVoltage(uint16_t voltage)
uint16_t powerSourceMinVoltage() 

batteryChargeCurrent - SystemPowerConfiguration

Sets the battery charge current. The actual charge current is the lesser of powerSourceMaxCurrent and batteryChargeCurrent. The value is milliamps (mA).

The default is 896 mA.

// PROTOTYPES
SystemPowerConfiguration& batteryChargeCurrent(uint16_t current)
uint16_t batteryChargeCurrent() const 

batteryChargeVoltage - SystemPowerConfiguration

Sets the battery charge termination voltage. The value is in millivolts or 1000ths of a volt, so 3880 is 3.880 volts. When the battery reaches this voltage, charging is stopped.

The default is 4112 (4.112V).

// PROTOTYPES
SystemPowerConfiguration& batteryChargeVoltage(uint16_t voltage)
uint16_t batteryChargeVoltage() const

socBitPrecision() - SystemPowerConfiguration

Since 5.9.0:

The value returned by the fuel gauge chip may have a different number of bits of precision depending on whether it's a MAX17043 (18, the default) or MAX17048 (19), but the chips are otherwise very similar. If you are building your own SoM base board, this allows you to use a MAX17048 fuel gauge chip and still get correct values.

// PROTOTYPES
SystemPowerConfiguration& socBitPrecision(uint8_t bits) 
uint8_t socBitPrecision()

auxiliaryPowerControlPin() - SystemPowerConfiguration

Since 5.9.0:

Devices using the Particle Power Module include a 3V3_AUX power output that can be controlled by a GPIO. On the M.2 SoM breakout board, this powers the Feather connector. On the Muon, it powers the Ethernet port, LoRaWAN module, 40-pin expansion HAT connector, and QWIIC connector.

The main reason for this is that until the PMIC is configured, the input current with no battery connected is limited to 100 mA. This is insufficient for the M-SoM to boot when using a peripheral that requires a lot of current, like the WIZnet W5500 Ethernet module. The system power manager prevents turning on 3V3_AUX until after the PMIC is configured and the PMIC has negotiated a higher current from the USB host (if powered by USB).

This setting is persistent and only needs to be set once. In fact, the PMIC initialization normally occurs before user firmware is run. This is also necessary because if you are using Ethernet and enter safe mode (breathing magenta), it's necessary to enable 3V3_AUX so if you are using Ethernet, you can still get OTA updates while in safe mode.

After changing the auxiliary power configuration you must reset the device.

// PROTOTYPES
SystemPowerConfiguration& auxiliaryPowerControlPin(uint8_t pin, bool activeLevel = 1) 
uint8_t auxiliaryPowerControlPin() const
uint8_t auxiliaryPowerControlActiveLevel()

// EXAMPLE - Muon
SystemPowerConfiguration powerConfig = System.getPowerConfiguration();
powerConfig.auxiliaryPowerControlPin(D7).interruptPin(A7);
System.setPowerConfiguration(powerConfig);

// EXAMPLE - M.2 SoM Breakout board
SystemPowerConfiguration powerConfig = System.getPowerConfiguration();
powerConfig.auxiliaryPowerControlPin(D23).interruptPin(A6);
System.setPowerConfiguration(powerConfig);

interruptPin() - SystemPowerConfiguration

Since 5.9.0:

This call allows the use of an alternate GPIO pin for the PMIC and fuel gauge interrupt input.

// PROTOTYPES
SystemPowerConfiguration& interruptPin(uint8_t pin)
uint8_t interruptPin() const

SystemPowerFeature

SerialLogHandler logHandler;

void setup() {
    // Apply a custom power configuration
    SystemPowerConfiguration conf;

    conf.feature(SystemPowerFeature::DISABLE_CHARGING);
    int res = System.setPowerConfiguration(conf);
    Log.info("setPowerConfiguration=%d", res);
    // returns SYSTEM_ERROR_NONE (0) in case of success

    // Settings are persisted, you normally wouldn't do this on every startup.
}

System power features are enabled or disabled using the SystemPowerConfiguration::feature() method. The settings are saved in non-volatile storage so you do not need to set them on every startup.

SystemPowerFeature::PMIC_DETECTION

For devices with an external PMIC and Fuel Gauge like the B-Series SoM, enables detection of the bq24195 PMIC connected by I2C to the primary I2C interface (Wire). Since this requires the use of I2C, you should not use pins D0 and D1 for GPIO when using PMIC_DETECTION.

SystemPowerFeature::USE_VIN_SETTINGS_WITH_USB_HOST

Normally, if a USB host is detected, the power limit settings will be determined by DPDM, the negotiation between the USB host and the PMIC to determine, for example, the maximum current available. If this feature is enabled, the VIN settings are used even when a USB host is detected. This is normally done if you are using USB for debugging but still have a power supply connected to VIN.

SystemPowerFeature::DISABLE_CHARGING

Since 3.0.0:

Disables LiPo battery charging. This may be useful if:

• You are manually controlling charging, for example based on an external temperature sensor
• You are using a non-rechargeable battery
• You are powering the device from a power supply connected to the Li+ pin instead of VIN

SystemPowerFeature::DISABLE

Disables the system power management features. If you set this mode you must manually set the values in the PMIC directly.

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
    // Apply a custom power configuration
    SystemPowerConfiguration conf;

    conf.powerSourceMaxCurrent(900) 
        .powerSourceMinVoltage(4300) 
        .batteryChargeCurrent(850) 
        .batteryChargeVoltage(4210);

    int res = System.setPowerConfiguration(conf); 
    Log.info("setPowerConfiguration=%d", res);
    // returns SYSTEM_ERROR_NONE (0) in case of success

    // Settings are persisted, you normally wouldn't do this on every startup.
}

void loop() {
    {
        PMIC power(true);
        Log.info("Current PMIC settings:");
        Log.info("VIN Vmin: %u", power.getInputVoltageLimit());
        Log.info("VIN Imax: %u", power.getInputCurrentLimit());
        Log.info("Ichg: %u", power.getChargeCurrentValue());
        Log.info("Iterm: %u", power.getChargeVoltageValue());

        int powerSource = System.powerSource();
        int batteryState = System.batteryState();
        float batterySoc = System.batteryCharge();

        constexpr char const* batteryStates[] = {
            "unknown", "not charging", "charging",
            "charged", "discharging", "fault", "disconnected"
        };
        constexpr char const* powerSources[] = {
            "unknown", "vin", "usb host", "usb adapter",
            "usb otg", "battery"
        };

        Log.info("Power source: %s", powerSources[std::max(0, powerSource)]);
        Log.info("Battery state: %s", batteryStates[std::max(0, batteryState)]);
        Log.info("Battery charge: %f", batterySoc);
    }

    delay(2000);
}

To reset all settings to the default values:

// Reset power manager settings to default values

void setup() {
    // To restore the default configuration
    SystemPowerConfiguration conf;
    System.setPowerConfiguration(conf);
}

B-Series SoM

By default, on the B-Series SoM, the Tinker application firmware enables the use of the bq24195 PMIC and MAX17043 fuel gauge. This in turn uses I2C (D0 and D1) and pin A6 (PM_INT). If you are not using the PMIC and fuel gauge and with to use these pins for other purposes, be sure to disable system power configuration. This setting is persistent, so you may want to disable it with your manufacturing firmware only.

System.setPowerConfiguration(SystemPowerConfiguration());

PMIC (Power Management IC)

You should generally set the PMIC settings such as input volage, input current limit, charge current, and charge termination voltage using the Power Manager API, above. If you directly set the PMIC, the settings will likely be overridden by the system.

To find out the current power source (battery, VIN, USB), see System.powerSource(). To find out if the battery is charging, discharging, disconnected, etc., see System.batteryState().

Note: This is advanced IO and for experienced users. This controls the LiPo battery management system and is handled automatically by the Device OS.

Note:

PMIC() constructor

// PROTOTYPE
PMIC(bool _lock=false);

You can declare the PMIC object either as a global variable, or a stack-allocated local variable. If you use a stack local, pass true as the parameter to the constructor. This will automatically call lock() from the constructor and unlock() from the destructor.

begin()

bool begin();

getVersion()

byte getVersion();

getSystemStatus()

byte getSystemStatus();

getFault()

byte getFault();

lock()

void lock();

You should always call lock() and unlock(), use WITH_LOCK(), or stack allocate a PMIC object nad pass true to the constructor.

Since the PMIC can be accessed from both the system and user threads, locking it assures that a PMIC opertation will not be interrupted by another thread.

unlock()

void unlock();

Input source control register

readInputSourceRegister()

byte readInputSourceRegister(void);

enableBuck()

bool enableBuck(void);

disableBuck()

bool disableBuck(void);

setInputCurrentLimit()

bool setInputCurrentLimit(uint16_t current);

getInputCurrentLimit()

byte getInputCurrentLimit(void);

setInputVoltageLimit()

bool setInputVoltageLimit(uint16_t voltage);

getInputVoltageLimit()

byte getInputVoltageLimit(void);

Power on configuration reg

enableCharging()

bool enableCharging(void);

disableCharging()

bool disableCharging(void);

enableOTG()

bool enableOTG(void);

disableOTG()

bool disableOTG(void);

resetWatchdog()

bool resetWatchdog(void);

setMinimumSystemVoltage()

bool setMinimumSystemVoltage(uint16_t voltage);

getMinimumSystemVoltage()

uint16_t getMinimumSystemVoltage();

readPowerONRegister()

byte readPowerONRegister(void);

Charge current control reg

setChargeCurrent()

bool setChargeCurrent(bool bit7, bool bit6, bool bit5, bool bit4, bool bit3, bool bit2);

The total charge current is the 512mA + the combination of the current that the following bits represent

• bit7 = 2048mA
• bit6 = 1024mA
• bit5 = 512mA
• bit4 = 256mA
• bit3 = 128mA
• bit2 = 64mA

For example, to set a 1408 mA charge current:

PMIC pmic;
pmic.setChargeCurrent(0,0,1,1,1,0);

• 512mA + (0+0+512mA+256mA+128mA+0) = 1408mA

getChargeCurrent()

byte getChargeCurrent(void);

Returns the charge current register. This is the direct register value from the BQ24195 PMIC. The bits in this register correspond to the bits you pass into setChargeCurrent.

• bit7 is the MSB, value 0x80
• bit2 is the LSB, value 0x04

Precharge/termination current control reg

setPreChargeCurrent()

bool setPreChargeCurrent();

getPreChargeCurrent()

byte getPreChargeCurrent();

setTermChargeCurrent()

bool setTermChargeCurrent();

getTermChargeCurrent()

byte getTermChargeCurrent();

Charge voltage control reg

setChargeVoltage()

bool setChargeVoltage(uint16_t voltage);

Voltage can be:

• 4112 (4.112 volts), the default
• 4208 (4.208 volts), only safe at lower temperatures

The default charge voltage is 4112, which corresponds to 4.112 volts.

You can also set it 4208, which corresponds to 4.208 volts. This higher voltage should not be used if the battery will be charged in temperatures exceeding 45°C. Using a higher charge voltage will allow the battery to reach a higher state-of-charge (SoC) but could damage the battery at high temperatures.

void setup() {
    PMIC power;
    power.setChargeVoltage(4208);
}

Note: Do not use 4208 with Device OS 0.4.8 or 0.5.0, as a bug will cause an incorrect, even higher, voltage to be used.

getChargeVoltageValue()

uint16_t getChargeVoltageValue();

Returns the charge voltage constant that could pass into setChargeVoltage, typically 4208 or 4112.

getChargeVoltage()

byte getChargeVoltage();

Returns the charge voltage register. This is the direct register value from the BQ24195 PMIC.

• 155, 0x9b, 0b10011011, corresponds to 4112
• 179, 0xb3, 0b10110011, corresponds to 4208

Charge timer control reg

readChargeTermRegister()

byte readChargeTermRegister();

disableWatchdog()

bool disableWatchdog(void);

setWatchdog()

bool setWatchdog(byte time);

Thermal regulation control reg

setThermalRegulation()

bool setThermalRegulation();

getThermalRegulation()

byte getThermalRegulation();

Misc operation control reg

readOpControlRegister()

byte readOpControlRegister();

enableDPDM()

bool enableDPDM(void);

disableDPDM()

bool disableDPDM(void);

enableBATFET()

bool enableBATFET(void);

disableBATFET()

bool disableBATFET(void);

safetyTimer()

bool safetyTimer();

enableChargeFaultINT()

bool enableChargeFaultINT();

disableChargeFaultINT()

bool disableChargeFaultINT();

enableBatFaultINT()

bool enableBatFaultINT();

disableBatFaultINT()

bool disableBatFaultINT();

System status register

getVbusStat()

byte getVbusStat();

getChargingStat()

byte getChargingStat();

getDPMStat()

bool getDPMStat();

isPowerGood()

bool isPowerGood(void);

isHot()

bool isHot(void);

getVsysStat()

bool getVsysStat();

Serial

(inherits from Stream)

• (1) Serial2 on the Photon and Electron uses the same pins as the RGB status LED, and cannot be used without physically disconnecting the status LED on the device by removing the LED or current limiting resistors.
• (2) Serial1 on the Tracker One shares the same pins as Wire3 on the external M8 connector.
• Serial is a USB serial emulation, not a hardware UART.
• USBSerial1 is available on Device OS 0.6.0 and later, and is a second USB serial emulation.

There are also other interfaces that can be used for communication:

Serial: This channel communicates through the USB port and when connected to a computer, will show up as a virtual COM port.

// EXAMPLE USAGE - NOT RECOMMENDED
void setup()
{
  Serial.begin();
  Serial.println("Hello World!");
}

// EXAMPLE USAGE - PREFERRED
SerialLogHandler logHandler;

void setup()
{
  Log.info("Hello World!");
}

Instead of using Serial directly, you should use it using the the SerialLogHandler if you are writing debugging messages. Using the Log method makes it easy to switch between Serial and Serial1 (or both!) as well as providing thread-safety. It also allows log messages to be intercepted by code, and even saved to things like SD cards, with additional libraries.

You should also avoid mixing the use of Serial.printlnf and Log.info (and similar calls). Since Serial.print is not thread safe, it can interfere with the use of Log calls.

Serial1: This channel is available via the device's TX and RX pins.

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

P2 and Photon 2 Devices (RTL872x):

M-SoM Devices (RTL872x):

Serial2: On the P2, Photon 2, and M-SoM, this channel is available. It uses the same pins as SPI1, so you can only use Serial2 or SPI1, not both.

On the Photon, this channel is optionally available via pins 28/29 (RGB LED Blue/Green). These pins are accessible via the pads on the bottom of the PCB See PCB Land Pattern. The Blue and Green current limiting resistors should be removed. If the user enables Serial2, they should also consider using RGB.onChange() to move the RGB functionality to an external RGB LED on some PWM pins.

On the Electron, this channel is shared with the RGB Green (TX) and Blue (RX) LED pins. If used for Serial2, the LED or current limiting resistors should be removed. As there are no test pads for these LED pins on the Electron, Serial2 will be difficult to use.

On the P1 and E-Series, this channel is shared with the RGB Green (TX) and Blue (RX) LED pins. Since you supply your own LEDs on these devices, you can move them to other pins using RGB.mirrorTo().

Other devices do not support Serial2. On the Argon and Boron, the hardware port is used to communicate with the network coprocessor (NCP) and is not available for user use.

To use Serial2, add #include "Serial2/Serial2.h" near the top of your app's main code file.

Serial3: This channel is optionally available on the P2 and Photon 2 only. It optionally supports hardware flow control. To use Serial3, add #include "Serial3/Serial3.h" near the top of your app's main code file.

Serial4: This channel is optionally available via the Electron and E-Series C3(TX) and C2(RX) pins. To use Serial4, add #include "Serial4/Serial4.h" near the top of your app's main code file. This port is not available on other devices.

Serial5: This channel is optionally available via the Electron and E-Series C1(TX) and C0(RX) pins. To use Serial5, add #include "Serial5/Serial5.h" near the top of your app's main code file. This port is not available on other devices.

USBSerial1: Available on Gen 2 (Photon, P1, Electron, E-Series) with Device OS 0.6.0. and later: This channel communicates through the USB port and when connected to a computer, will show up as a second virtual COM port. This channel is disabled by default.

To use the Serial1 or other hardware UART pins to communicate with your personal computer, you will need an additional USB-to-serial adapter. To use them to communicate with an external TTL serial device, connect the TX pin to your device's RX pin, the RX to your device's TX pin, and ground.

// EXAMPLE USAGE
void setup()
{
  Serial1.begin(9600);

  Serial1.println("Hello World!");
}

// EXAMPLE USAGE Serial4 on Electron and E-Series
#include "Serial4/Serial4.h"

void setup()
{
  Serial4.begin(9600);

  Serial4.println("Hello World!");
}

To use the hardware serial pins of (Serial1, etc.) to communicate with your personal computer, you will need an additional USB-to-serial adapter. To use them to communicate with an external TTL serial device, connect the TX pin to your device's RX pin, the RX to your device's TX pin, and the ground of your device to your device's ground.

NOTE: Please take into account that the voltage levels on these pins operate at 0V to 3.3V and should not be connected directly to a computer's RS232 serial port which operates at +/- 12V and will damage the device.

NOTE: On Windows 10, using USBSerial1 on the Electron, E-Series, and P1 may not be reliable due to limitations of the USB peripheral used for those 2 devices. Characters may be dropped between the computer and device. USBSerial1 is reliable on other operating systems and also on the Photon. USBSerial1 is not available on Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker SoM).

For more information about serial ports, see learn more about serial.

begin()

Enables serial channel with specified configuration.

// SYNTAX
Serial.begin();          // via USB port

// Photon, P1, Electron, and E-Series only
USBSerial1.begin();      // via USB port 

Serial1.begin(speed);         // via TX/RX pins
Serial1.begin(speed, config); //  "

Serial1.begin(9600, SERIAL_9N1); // via TX/RX pins, 9600 9N1 mode
Serial1.begin(9600, SERIAL_DATA_BITS_8 | SERIAL_STOP_BITS_1_5 | SERIAL_PARITY_EVEN); // via TX/RX pins, 9600 8E1.5

// P2, Photon 2, Photon, P1, Electron, and E-Series
#include "Serial2/Serial2.h"
Serial2.begin(speed);         // RGB-LED green(TX) and blue (RX) pins
Serial2.begin(speed, config); //  "

Serial2.begin(9600);         // via RGB Green (TX) and Blue (RX) LED pins
Serial2.begin(9600, SERIAL_DATA_BITS_8 | SERIAL_STOP_BITS_1_5 | SERIAL_PARITY_EVEN); // via RGB Green (TX) and Blue (RX) LED pins, 9600 8E1.5

// Electron and E-Series only
#include "Serial4/Serial4.h"
Serial4.begin(speed);         // via C3(TX)/C2(RX) pins
Serial4.begin(speed, config); //  "

// Electron and E-Series only
#include "Serial5/Serial5.h"
Serial5.begin(speed);         // via C1(TX)/C0(RX) pins
Serial5.begin(speed, config); //  "

Parameters:

• speed: parameter that specifies the baud rate (long) (optional for Serial and USBSerial1
• config: parameter that specifies the number of data bits used, parity and stop bits (long) (not used with Serial and USBSerial1)

// EXAMPLE USAGE
void setup()
{
  Serial.begin(9600);   // open serial over USB

  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  Serial1.begin(9600);  // open serial over TX and RX pins

  Serial.println("Hello Computer");
  Serial1.println("Hello Serial 1");
}

void loop() {}

Since 0.5.0: 28800 baudrate set by the Host on Serial will put the device in Listening Mode, where a YMODEM download can be started by additionally sending an f character. Baudrate 14400 can be used to put the device into DFU Mode.

When using hardware serial channels (Serial1, Serial2, etc.), the configuration of the serial channel may also specify the number of data bits, stop bits, parity, flow control and other settings. The default is SERIAL_8N1 (8 data bits, no parity and 1 stop bit) and does not need to be specified to achieve this configuration. To specify one of the following configurations, add one of these defines as the second parameter in the begin() function, e.g. Serial1.begin(9600, SERIAL_8E1); for 8 data bits, even parity and 1 stop bit.

Pre-defined Serial configurations available:

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

// EXAMPLE USAGE
STARTUP(USBSerial1.begin());
void setup()
{
  while(!Serial.isConnected())
    Particle.process();
  Serial.println("Hello Serial!");

  while(!USBSerial1.isConnected())
    Particle.process();
  USBSerial1.println("Hello USBSerial1!");
}

end()

Disables serial channel.

When used with hardware serial channels (Serial1, Serial2, etc.), disables serial communication, allowing channel's RX and TX pins to be used for general input and output. To re-enable serial communication, call SerialX.begin().

Since 0.6.0:

When used with USB serial channels (Serial or USBSerial1), end() will cause the device to quickly disconnect from Host and connect back without the selected serial channel.

// SYNTAX
Serial1.end();

available()

Get the number of bytes (characters) available for reading from the serial port. This is data that's already arrived and stored in the serial receive buffer.

The receive buffer size for hardware UART serial channels (Serial1, Serial2, etc.) is 128 bytes on Gen 3 (Argon, Boron, B-Series SoM, Tracker SoM) and 64 or 128 bytes depending on the UART mode on Gen 2 (Photon, P1, Electron, E-Series). Since 3.2.0: See also acquireSerial1Buffer.

For USB serial (Serial, USBSerial1), the receive buffer is 256 bytes. Also see acquireSerialBuffer acquireSerial1Buffer.

// EXAMPLE USAGE
void setup()
{
  Serial.begin(9600);
  Serial1.begin(9600);

}

void loop()
{
  // read from port 0, send to port 1:
  if (Serial.available())
  {
    int inByte = Serial.read();
    Serial1.write(inByte);
  }
  // read from port 1, send to port 0:
  if (Serial1.available())
  {
    int inByte = Serial1.read();
    Serial.write(inByte);
  }
}

availableForWrite()

Since 0.4.9: Available on Serial1, Serial2, etc..

Since 0.5.0: Available on USB Serial (Serial)

Since 0.6.0: Available on USBSerial1

Retrieves the number of bytes (characters) that can be written to this serial port without blocking.

If blockOnOverrun(false) has been called, the method returns the number of bytes that can be written to the buffer without causing buffer overrun, which would cause old data to be discarded and overwritten.

acquireSerialBuffer()

// SYNTAX
HAL_USB_USART_Config acquireSerialBuffer()
{
  HAL_USB_USART_Config conf = {0};

  // The usable buffer size will be 128
  static uint8_t serial_rx_buffer[129];
  static uint8_t serial_tx_buffer[129];

  conf.rx_buffer = serial_rx_buffer;
  conf.tx_buffer = serial_tx_buffer;
  conf.rx_buffer_size = 129;
  conf.tx_buffer_size = 129;

  return conf;
}

HAL_USB_USART_Config acquireUSBSerial1Buffer()
{
  HAL_USB_USART_Config conf = {0};

  // The usable buffer size will be 128
  static uint8_t usbserial1_rx_buffer[129];
  static uint8_t usbserial1_tx_buffer[129];

  conf.rx_buffer = usbserial1_rx_buffer;
  conf.tx_buffer = usbserial1_tx_buffer;
  conf.rx_buffer_size = 129;
  conf.tx_buffer_size = 129;

  return conf;
}

Since 0.6.0:

It is possible for the application to allocate its own buffers for Serial (USB serial) by implementing acquireSerialBuffer. Minimum receive buffer size is 65 bytes.

On Gen 2 devices (Photon, P1, Electron. E-Series), the USBSerial1 receive buffer can be resized using acquireUSBSerial1Buffer. Minimum receive buffer size is 65 bytes.

Since 3.2.0: This is also available for hardware UART ports like Serial1, Serial2, etc, see acquireSerial1Buffer.

acquireSerial1Buffer()

// SYNTAX
hal_usart_buffer_config_t acquireSerial1Buffer()
{
#if !HAL_PLATFORM_USART_9BIT_SUPPORTED
    const size_t bufferSize = 64;
#else
    // If 9-bit mode is supported (e.g. on Gen 2 platforms)
    // and it's planned to use this mode, it's necessary to allocate
    // 2x the number of bytes.
    const size_t bufferSize = 64 * sizeof(uint16_t);
#endif // HAL_PLATFORM_USART_9BIT_SUPPORTED
    hal_usart_buffer_config_t config = {
        .size = sizeof(hal_usart_buffer_config_t),
        .rx_buffer = new (std::nothrow) uint8_t[bufferSize],
        .rx_buffer_size = bufferSize,
        .tx_buffer = new (std::nothrow) uint8_t[bufferSize],
        .tx_buffer_size = bufferSize
    };

    return config;
}

hal_usart_buffer_config_t acquireSerial2Buffer()
{
    const size_t bufferSize = 64;
    hal_usart_buffer_config_t config = {
        .size = sizeof(hal_usart_buffer_config_t),
        .rx_buffer = new (std::nothrow) uint8_t[bufferSize],
        .rx_buffer_size = bufferSize,
        .tx_buffer = new (std::nothrow) uint8_t[bufferSize],
        .tx_buffer_size = bufferSize
    };

    return config;
}

Since 3.2.0:

It is possible for the application to allocate its own buffers for Serial1 and other hardware UART ports by implementing acquireSerial1Buffer, acquireSerial2Buffer etc. Minimum receive buffer size is 64 bytes.

Depending on UART mode it might be required to allocate double the number of bytes (e.g. for 9-bit modes).

blockOnOverrun()

Since 0.4.9: Available on Serial1, Serial2, ....

Since 0.5.0: Available on USB Serial (Serial)

Since 0.6.0: Available on USBSerial1 on Gen 2 devices (Photon, P1, Electron, E-Series)

Defines what should happen when calls to write()/print()/println()/printlnf() that would overrun the buffer.

• blockOnOverrun(true) - this is the default setting. When there is no room in the buffer for the data to be written, the program waits/blocks until there is room. This avoids buffer overrun, where data that has not yet been sent over serial is overwritten by new data. Use this option for increased data integrity at the cost of slowing down realtime code execution when lots of serial data is sent at once.

• blockOnOverrun(false) - when there is no room in the buffer for data to be written, the data is written anyway, causing the new data to replace the old data. This option is provided when performance is more important than data integrity.

// EXAMPLE - fast and furious over Serial1
Serial1.blockOnOverrun(false);
Serial1.begin(115200);

serialEvent()

A family of application-defined functions that are called whenever there is data to be read from a serial peripheral.

• serialEvent: called when there is data available from Serial
• usbSerialEvent1: called when there is data available from USBSerial1 if this port is available
• serialEvent1: called when there is data available from Serial1
• serialEvent2: called when there is data available from Serial2 if this port is available
• serialEvent4: called when there is data available from Serial4 if this port is available
• serialEvent5: called when there is data available from Serial5 if this port is available

The serialEvent functions are called in between calls to the application loop(). This means that if loop() runs for a long time due to delay() calls or other blocking calls the serial buffer might become full between subsequent calls to serialEvent and serial characters might be lost. Avoid long delay() calls in your application if using serialEvent.

Since serialEvent functions are an extension of the application loop, it is ok to call any functions that you would also call from loop(). Because of this, there is little advantage to using serial events over just reading serial from loop().

// EXAMPLE - echo all characters typed over serial

void setup()
{
   Serial.begin(9600);
}

void serialEvent()
{
    char c = Serial.read();
    Serial.print(c);
}

peek()

Returns the next byte (character) of incoming serial data without removing it from the internal serial buffer. That is, successive calls to peek() will return the same character, as will the next call to read().

// SYNTAX
Serial.peek();
Serial1.peek();

peek() returns the first byte of incoming serial data available (or -1 if no data is available) - int

write()

Writes binary data to the serial port. This data is sent as a byte or series of bytes; to send the characters representing the digits of a number use the print() function instead.

// SYNTAX
Serial.write(val);
Serial.write(str);
Serial.write(buf, len);

// EXAMPLE USAGE

void setup()
{
  Serial.begin(9600);
}

void loop()
{
  Serial.write(45); // send a byte with the value 45

  int bytesSent = Serial.write(“hello”); //send the string “hello” and return the length of the string.
}

Parameters:

• val: a value to send as a single byte
• str: a string to send as a series of bytes
• buf: an array to send as a series of bytes
• len: the length of the buffer

write() will return the number of bytes written, though reading that number is optional.

read()

Reads incoming serial data.

// SYNTAX
Serial.read();
Serial1.read();

read() returns the first byte of incoming serial data available (or -1 if no data is available) - int

// EXAMPLE USAGE
int incomingByte = 0; // for incoming serial data

void setup() {
  Serial.begin(9600); // opens serial port, sets data rate to 9600 bps
}

void loop() {
  // send data only when you receive data:
  if (Serial.available() > 0) {
    // read the incoming byte:
    incomingByte = Serial.read();

    // say what you got:
    Serial.print("I received: ");
    Serial.println(incomingByte, DEC);
  }
}

print()

Prints data to the serial port as human-readable ASCII text. This command can take many forms. Numbers are printed using an ASCII character for each digit. Floats are similarly printed as ASCII digits, defaulting to two decimal places. Bytes are sent as a single character. Characters and strings are sent as is. For example:

• Serial.print(78) gives "78"
• Serial.print(1.23456) gives "1.23"
• Serial.print('N') gives "N"
• Serial.print("Hello world.") gives "Hello world."

An optional second parameter specifies the base (format) to use; permitted values are BIN (binary, or base 2), OCT (octal, or base 8), DEC (decimal, or base 10), HEX (hexadecimal, or base 16). For floating point numbers, this parameter specifies the number of decimal places to use. For example:

• Serial.print(78, BIN) gives "1001110"
• Serial.print(78, OCT) gives "116"
• Serial.print(78, DEC) gives "78"
• Serial.print(78, HEX) gives "4E"
• Serial.println(1.23456, 0) gives "1"
• Serial.println(1.23456, 2) gives "1.23"
• Serial.println(1.23456, 4) gives "1.2346"

println()

Prints data to the serial port as human-readable ASCII text followed by a carriage return character (ASCII 13, or '\r') and a newline character (ASCII 10, or '\n'). This command takes the same forms as Serial.print().

// SYNTAX
Serial.println(val);
Serial.println(val, format);

Parameters:

• val: the value to print - any data type
• format: specifies the number base (for integral data types) or number of decimal places (for floating point types)

println() returns the number of bytes written, though reading that number is optional - size_t (long)

// EXAMPLE
//reads an analog input on analog in A0, prints the value out.

int analogValue = 0;    // variable to hold the analog value

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);
}

void loop() {
  // read the analog input on pin A0:
  analogValue = analogRead(A0);

  // print it out in many formats:
  Serial.println(analogValue);       // print as an ASCII-encoded decimal
  Serial.println(analogValue, DEC);  // print as an ASCII-encoded decimal
  Serial.println(analogValue, HEX);  // print as an ASCII-encoded hexadecimal
  Serial.println(analogValue, OCT);  // print as an ASCII-encoded octal
  Serial.println(analogValue, BIN);  // print as an ASCII-encoded binary

  // delay 10 milliseconds before the next reading:
  delay(10);
}

printf()

Since 0.4.6:

Provides printf-style formatting over serial.

printf allows strings to be built by combining a number of values with text.

Serial.printf("Reading temperature sensor at %s...", Time.timeStr().c_str());
float temp = readTemp();
Serial.printf("the temperature today is %f Kelvin", temp);
Serial.println();

Running this code prints:

Reading temperature sensor at Thu 01 Oct 2015 12:34...the temperature today is 293.1 Kelvin.

The last printf() call could be changed to printlnf() to avoid a separate call to println().

printlnf()

Since 0.4.6:

formatted output followed by a newline. Produces the same output as printf which is then followed by a newline character, so to that subsequent output appears on the next line.

flush()

Waits for the transmission of outgoing serial data to complete.

// SYNTAX
Serial.flush();
Serial1.flush();

flush() neither takes a parameter nor returns anything.

halfduplex()

Puts Serial1 into half-duplex mode. In this mode both the transmit and receive are on the TX pin. This mode can be used for a single wire bus communications scheme between microcontrollers.

// SYNTAX
Serial1.halfduplex(true);  // Enable half-duplex mode
Serial1.halfduplex(false); // Disable half-duplex mode

// EXAMPLE
// Initializes Serial1 at 9600 baud and enables half duplex mode

Serial1.begin(9600);
Serial1.halfduplex(true);

halfduplex() takes one argument: true enables half-duplex mode, false disables half-duplex mode

halfduplex() returns nothing

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

isConnected()

// EXAMPLE USAGE
void setup()
{
  Serial.begin();   // open serial over USB
  while(!Serial.isConnected()) // wait for Host to open serial port
    Particle.process();

  Serial.println("Hello there!");
}

Another technique is to use waitFor which makes it easy to time-limit the waiting period.

// EXAMPLE USAGE
void setup()
{
  Serial.begin();   // open serial over USB

  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  Serial.println("Hello there!");
}

Since 0.5.3 Available on Serial.

Since 0.6.0 Available on Serial and USBSerial1.

Used to check if host has serial port (virtual COM port) open.

Returns:

• true when Host has virtual COM port open.

lock()

The USB serial objects does not have built-in thread-safety. If you want to read or write the object from multiple threads, including from a software timer, you must lock and unlock it to prevent data from multiple thread from being interleaved or corrupted.

A call to lock lock() must be balanced with a call to unlock() and not be nested. To make sure every lock is released, it's good practice to use WITH_LOCK like this:

// EXAMPLE USAGE
void loop()
{
  WITH_LOCK(Serial) {
    Serial.println("Hello there!");
  }
}

Never use lock() or WITH_LOCK() within a SINGLE_THREADED_BLOCK() as deadlock can occur.

The UART serial objects such as Serial1 allow multiple threads to read and write at the byte level. They do not support WITH_LOCK, however, so if you need to control access at the line, transaction, block, etc. level you need to implement an external mutex.

unlock()

Unlocks the Serial mutex. See lock().

Mouse

// EXAMPLE USAGE
// Use STARTUP() macro to avoid USB disconnect/reconnect (see begin() documentation)
STARTUP(Mouse.begin());

void setup() {
  // Set screen size to 1920x1080 (to scale [0, 32767] absolute Mouse coordinates)
  Mouse.screenSize(1920, 1080);
  // Move mouse to the center of the screen and click left button
  Mouse.moveTo(1920 / 2, 1080 / 2);
  Mouse.click(MOUSE_LEFT);
  // Move mouse from the current position by 100 points (not pixels) left
  Mouse.move(-100, 0);
  // Press right mouse button (and leave it pressed)
  Mouse.press(MOUSE_RIGHT);
  // Scroll wheel in the negative direction
  Mouse.scroll(-127);
  // Release right mouse button
  Mouse.release(MOUSE_RIGHT);
}

void loop() {
}

Since 0.6.0:

This object allows devices to act as a native USB HID Mouse.

In terms of USB HID, the device presents itself as two separate devices: Mouse (supporting relative movement) and Digitizer (supporting absolute movement).

Full capabilities include:

• Relative XY movement [-32767, 32767]
• Absolute XY movement [0, 32767]
• 3-buttons (left, right, middle)
• Wheel [-127, 127]

NOTE: Linux X11 doesn't support HID devices reporting both absolute and relative coordinates. By default only absolute movement is possible by using Mouse.moveTo(). In order for regular relative Mouse.move() to work, a call to Mouse.enableMoveTo(false) is required.

Keyboard and Mouse support is only available on some devices and Device OS versions:

begin()

// SYNTAX
Mouse.begin();

Initializes Mouse library and enables USB HID stack.

// Example
STARTUP(Mouse.begin());
void setup() {
  // At this point the device is already connected to Host with Mouse enabled
}

NOTE: When Mouse.begin() is called in setup() or during normal application execution, the device will quickly disconnect from Host and connect back with USB HID enabled. If such behavior is undesirable, Mouse may be enabled with STARTUP() macro, which will force the device to connect to the Host after booting with Mouse already enabled.

This function takes no parameters and does not return anything.

end()

// SYNTAX
Mouse.end();

Disables USB Mouse functionality.

// Example
// Enable both Keyboard and Mouse on startup
STARTUP(Mouse.begin());
STARTUP(Keyboard.begin());

void setup() {
  // A call to Mouse.end() here will not cause the device to disconnect and connect back to the Host
  Mouse.end();
  // Disabling both Keyboard and Mouse at this point will trigger the behavior explained in NOTE.
  Keyboard.end();
}

NOTE: Calling Mouse.end() will cause the device to quickly disconnect from Host and connect back without USB HID enabled if Keyboard is disabled as well.

This function takes no parameters and does not return anything.

move()

// SYNTAX
Mouse.move(x, y);
Mouse.move(x, y, wheel);

Moves the cursor relative to the current position.

Parameters:

• x: amount to move along the X axis - int16_t [-32767, 32767]
• y: amount to move along the Y axis - int16_t [-32767, 32767]
• wheel: amount to move the scroll wheel - int8_t [-127, 127]

move() does not return anything.

moveTo()

// SYNTAX
Mouse.moveTo(x, y);

Moves the cursor to an absolute position. (0, 0) position is the top left corner of the screen. By default both X and Y axes span from 0 to 32767.

The default range [0, 32767] can be mapped to actual screen resolution by calling screenSize(). After the call to screenSize(), moveTo() will accept screen coordinates and automatically map them to the default range.

Parameters:

• x: X coordinate - uint16_t [0, 32767] (default)
• y: Y coordinate - uint16_t [0, 32767] (default)

moveTo() does not return anything.

scroll()

// SYNTAX
Mouse.scroll(wheel);

Scrolls the mouse wheel by the specified amount.

Parameters:

• wheel: amount to move the scroll wheel - int8_t [-127, 127]

scroll() does not return anything.

click()

// SYNTAX
Mouse.click();
Mouse.click(button);

Momentarily clicks specified mouse button at the current cursor position. A click is a press() quickly followed by release().

// EXAMPLE USAGE
// Click left mouse button
Mouse.click(MOUSE_LEFT);
// Click right mouse button
Mouse.click(MOUSE_RIGHT);
// Click middle mouse button
Mouse.click(MOUSE_MIDDLE);
// Click both left and right mouse buttons at the same time
Mouse.click(MOUSE_LEFT | MOUSE_RIGHT);

Parameters:

• button: which mouse button to click - uint8_t - MOUSE_LEFT (default), MOUSE_RIGHT, MOUSE_MIDDLE or any ORed (|) combination of buttons for simultaneous clicks

click() does not return anything.

press()

// SYNTAX
Mouse.press();
Mouse.press(button);

Presses specified mouse button at the current cursor position and holds it pressed. A press can be cancelled by release().

// EXAMPLE USAGE
// Press left mouse button
Mouse.press(MOUSE_LEFT);
// Press right mouse button
Mouse.press(MOUSE_RIGHT);
// Press middle mouse button
Mouse.press(MOUSE_MIDDLE);
// Press both left and right mouse buttons at the same time
Mouse.press(MOUSE_LEFT | MOUSE_RIGHT);

Parameters:

• button: which mouse button to press - uint8_t - MOUSE_LEFT (default), MOUSE_RIGHT, MOUSE_MIDDLE or any ORed (|) combination of buttons for simultaneous press

press() does not return anything.

release()

// SYNTAX
Mouse.release();
Mouse.release(button);

Releases previously pressed mouse button at the current cursor position.

// EXAMPLE USAGE
// Release left mouse button
Mouse.release(MOUSE_LEFT);
// Release right mouse button
Mouse.release(MOUSE_RIGHT);
// Release middle mouse button
Mouse.release(MOUSE_MIDDLE);
// Release both left and right mouse buttons at the same time
Mouse.release(MOUSE_LEFT | MOUSE_RIGHT);

Parameters:

• button: which mouse button to release - uint8_t - MOUSE_LEFT (default), MOUSE_RIGHT, MOUSE_MIDDLE or any ORed (|) combination of buttons to release simultaneously. To release all buttons simultaneously, MOUSE_ALL can also be used.

release() does not return anything.

isPressed()

// SYNTAX
Mouse.isPressed();
Mouse.isPressed(button);

This function checks the current state of mouse buttons and returns if they are currently pressed or not.

// EXAMPLE USAGE
bool pressed;
// Check if left mouse button is currently pressed
pressed = Mouse.isPressed(MOUSE_LEFT);
// Check if right mouse button is currently pressed
pressed = Mouse.isPressed(MOUSE_RIGHT);
// Check if middle mouse button is currently pressed
pressed = Mouse.isPressed(MOUSE_MIDDLE);

Parameters:

• button: which mouse button to check - uint8_t - MOUSE_LEFT (default), MOUSE_RIGHT, MOUSE_MIDDLE

isPressed() returns true if provided button is currently pressed.

screenSize()

// SYNTAX
Mouse.screenSize(screenWidth, screenHeight);
Mouse.screenSize(screenWidth, screenHeight,
                 marginLeft, marginRight,
                 marginTop, marginBottom);
Mouse.screenSize(screenWidth, screenHeight,
                 std::array<4, float>);

Maps the default absolute movement range [0, 32767] used by moveTo() to actual screen resolution. After setting the screen size, moveTo() will accept screen coordinates and automatically map them to the default range.

// EXAMPLE USAGE
// Use STARTUP() macro to avoid USB disconnect/reconnect (see begin() documentation)
STARTUP(Mouse.begin());

void setup() {
  // Set screen size to 1920x1080 (to scale [0, 32767] absolute Mouse coordinates)
  Mouse.screenSize(1920, 1080);
  // Move mouse to the center of the screen
  Mouse.moveTo(1920 / 2, 1080 / 2);
}

void loop() {
}

Parameters:

• screenWidth: screen width in pixels - uint16_t
• screenHeight: screen height in pixels - uint16_t
• marginLeft: (optional) left screen margin in percent (e.g. 10.0) - float
• marginRight: (optional) right screen margin in percent (e.g. 10.0) - float
• marginTop: (optional) top screen margin in percent (e.g. 10.0) - float
• marginBottom: (optional) bottom screen margin in percent (e.g. 10.0) - float

screenSize() does not return anything.

enableMoveTo()

// SYNTAX
Mouse.enableMoveTo(false);
Mouse.enableMoveTo(true);

Disables or enables absolute mouse movement (USB HID Digitizer).

// EXAMPLE USAGE
// Use STARTUP() macro to avoid USB disconnect/reconnect (see begin() documentation)
STARTUP(Mouse.begin());
// Disable absolute mouse movement
STARTUP(Mouse.enableMoveTo(false));

void setup() {
  // Move cursor by 100 points along X axis and by 100 points Y axis
  Mouse.move(100, 100);
  // Mouse.moveTo() calls do nothing
  Mouse.moveTo(0, 0);
}

void loop() {
}

NOTE: Linux X11 doesn't support HID devices reporting both absolute and relative coordinates. By default only absolute movement is possible by using Mouse.moveTo(). In order for regular relative Mouse.move() to work, a call to Mouse.enableMoveTo(false) is required.

NOTE: When Mouse.enableMoveTo() is called in setup() or during normal application execution, the device will quickly disconnect from Host and connect back with new settings. If such behavior is undesirable, moveTo() may be disable or enabled with STARTUP() macro, which will force the device to connect to the Host after booting with correct settings already in effect.

Parameters:

• state: true to enable absolute movement functionality, false to disable - bool

enableMoveTo() does not return anything.

Keyboard

// EXAMPLE USAGE
// Use STARTUP() macro to avoid USB disconnect/reconnect (see begin() documentation)
STARTUP(Keyboard.begin());

void setup() {
  // Type 'SHIFT+h', 'e', 'l', 'l', 'o', 'SPACE', 'w', 'o', 'r', 'l', 'd', 'ENTER'
  Keyboard.println("Hello world!");

  // Type 'SHIFT+t', 'e', 's', 't', 'SPACE', '1', '2', '3', '.', '4', '0', 'ENTER'
  Keyboard.printf("%s %.2f\n", "Test", 123.4f);

  // Quickly press and release Ctrl-Alt-Delete
  Keyboard.click(KEY_DELETE, MOD_LCTRL | MOD_LALT);

  // Press Ctrl, then Alt, then Delete and release them all
  Keyboard.press(KEY_LCTRL);
  Keyboard.press(KEY_LALT);
  Keyboard.press(KEY_DELETE);
  Keyboard.releaseAll();
}

void loop() {
}

Since 0.6.0:

This object allows your device to act as a native USB HID Keyboard.

Keyboard and Mouse support is only available on some devices and Device OS versions:

begin()

// SYNTAX
Keyboard.begin();

Initializes Keyboard library and enables USB HID stack.

// Example
STARTUP(Keyboard.begin());
void setup() {
  // At this point the device is already connected to Host with Keyboard enabled
}

NOTE: When Keyboard.begin() is called in setup() or during normal application execution, the device will quickly disconnect from Host and connect back with USB HID enabled. If such behavior is undesirable, Keyboard may be enabled with STARTUP() macro, which will force the device to connect to the Host after booting with Keyboard already enabled.

This function takes no parameters and does not return anything.

end()

// SYNTAX
Keyboard.end();

Disables USB Keyboard functionality.

// Example
// Enable both Keyboard and Mouse on startup
STARTUP(Mouse.begin());
STARTUP(Keyboard.begin());

void setup() {
  // A call to Mouse.end() here will not cause the device to disconnect and connect back to the Host
  Mouse.end();
  // Disabling both Keyboard and Mouse at this point will trigger the behavior explained in NOTE.
  Keyboard.end();
}

NOTE: Calling Keyboard.end() will cause the device to quickly disconnect from Host and connect back without USB HID enabled if Mouse is disabled as well.

This function takes no parameters and does not return anything.

write()

// SYNTAX
Keyboard.write(character);

Momentarily clicks a keyboard key. A click is a press() quickly followed by release(). This function works only with ASCII characters. ASCII characters are translated into USB HID keycodes according to the conversion table. For example ASCII character 'a' would be translated into 'a' keycode (leftmost middle row letter key on a QWERTY keyboard), whereas 'A' ASCII character would be sent as 'a' keycode with SHIFT modifier.

// EXAMPLE USAGE
STARTUP(Keyboard.begin());

void setup() {
  const char hello[] = "Hello world!\n";
  // This for-loop will type "Hello world!" followed by ENTER
  for (int i = 0; i < strlen(hello); i++) {
    Keyboard.write(hello[i]);
  }
}

This function is used by print(), println(), printf(), printlnf() which provide an easy way to type text.

Parameters:

• ch: ASCII character - char

write() does not return anything.

click()

// SYNTAX
Keyboard.click(key);
Keyboard.click(key, modifiers);

Momentarily clicks a keyboard key as well as one or more modifier keys (e.g. ALT, CTRL, SHIFT etc.). A click is a press() quickly followed by release(). This function works only with USB HID keycodes (defined in enum UsbKeyboardScanCode) and modifiers (defined in enum UsbKeyboardModifier). Keyboard implementation supports keycodes ranging from 0x04 (KEY_A / Keyboard a and A) to 0xDD (KEY_KPHEX / Keypad Hexadecimal).

// EXAMPLE USAGE
STARTUP(Keyboard.begin());

void setup() {
  // Quickly press and release Ctrl-Alt-Delete
  Keyboard.click(KEY_DELETE, MOD_LCTRL | MOD_LALT);
}

Parameters:

• key: USB HID key code (see enum UsbKeyboardScanCode) - uint16_t
• modifier: (optional) one or more ORed (|) USB HID modifier codes (see enum UsbKeyboardModifier - uint16_t

click() does not return anything.

press()

// SYNTAX
Keyboard.press(key);
Keyboard.press(key, modifier);

Presses specified keyboard key as well as one or more modifier keys and holds them pressed. A press can be cancelled by release() or releaseAll().

Up to 8 keys can be pressed simultaneously. Modifier keys (e.g. CTRL, ALT, SHIFT etc) are sent separately and do not add to the currently pressed key count, i.e. it is possible to press and keep pressing 8 regular keyboard keys and all the modifiers (LSHIFT, LALT, LGUI, LCTRL, RSHIFT, RALT, RSHIFT, RCTRL) at the same time.

See Keyboard.click() documentation for information about keycodes and modifier keys.

// EXAMPLE USAGE
STARTUP(Keyboard.begin());

void setup() {
  // Press Ctrl, then Alt, then Delete and release them all
  Keyboard.press(KEY_LCTRL);
  Keyboard.press(KEY_LALT);
  Keyboard.press(KEY_DELETE);
  Keyboard.releaseAll();
}

Parameters:

• key: USB HID key code (see enum UsbKeyboardScanCode) - uint16_t
• modifier: (optional) one or more ORed (|) USB HID modifier codes (see enum UsbKeyboardModifier - uint16_t

press() does not return anything.

release()

// SYNTAX
Keyboard.release(key);
Keyboard.release(key, modifier);

Releases previously pressed keyboard key as well as one or more modifier keys.

// EXAMPLE USAGE
STARTUP(Keyboard.begin());

void setup() {
  // Press Delete and two modifiers (left ALT and left CTRL) simultaneously
  Keyboard.press(KEY_DELETE, MOD_LCTRL | MOD_LALT);
  // Release Delete and two modifiers (left ALT and left CTRL) simultaneously
  Keyboard.release(KEY_DELETE, MOD_LCTRL | MOD_LALT);
}

See Keyboard.click() documentation for information about keycodes and modifier keys.

Parameters:

• key: USB HID key code (see enum UsbKeyboardScanCode) - uint16_t
• modifier: (optional) one or more ORed (|) USB HID modifier codes (see enum UsbKeyboardModifier - uint16_t

release() does not return anything.

releaseAll()

// SYNTAX
Keyboard.releaseAll();

Releases any previously pressed keyboard keys and modifier keys.

// EXAMPLE USAGE
STARTUP(Keyboard.begin());

void setup() {
  // Press Ctrl, then Alt, then Delete and release them all
  Keyboard.press(KEY_LCTRL);
  Keyboard.press(KEY_LALT);
  Keyboard.press(KEY_DELETE);
  Keyboard.releaseAll();
}

This function takes no parameters and does not return anything.

print()

See Keyboard.write() and Serial.print() documentation.

println()

See Keyboard.write() and Serial.println() documentation.

printf()

See Keyboard.write() and Serial.printf() documentation.

printlnf()

See Keyboard.write() and Serial.printlnf() documentation.

SPI

This object allows you to communicate with SPI ("Serial Peripheral Interface") devices, with the device as the master device.

SPI slave mode is supported as well (since DeviceOS 0.5.0). On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker SoM), SPI slave can only be used on SPI1.

The hardware SPI pin functions, which can be used via the SPI object, are mapped as follows:

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

P2 and Photon 2 Devices (RTL872x):

M-SoM Devices (RTL872x):

Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

begin()

Initializes the SPI bus by setting SCK, MOSI, and a user-specified slave-select pin to outputs, MISO to input. SCK is pulled either high or low depending on the configured SPI data mode (default high for SPI_MODE3). Slave-select is pulled high.

Note: The SPI firmware ONLY initializes the user-specified slave-select pin as an OUTPUT. The user's code must control the slave-select pin with digitalWrite() before and after each SPI transfer for the desired SPI slave device. Calling SPI.end() does NOT reset the pin mode of the SPI pins.

// SYNTAX
SPI.begin(ss);
SPI1.begin(ss);

// Example with no SS pin configured:
SPI.begin(PIN_INVALID);

Where, the parameter ss is the SPI device slave-select pin to initialize. The default SS pin varies by port and device, see above.

// Example using SPI1, with D5 as the SS pin:
SPI1.begin();
// or
SPI1.begin(D5);

begin(SPI_Mode, uint16_t)

Since 0.5.0:

Initializes the device SPI peripheral in master or slave mode.

Note: MISO, MOSI and SCK idle in high-impedance state when SPI peripheral is configured in slave mode and the device is not selected.

Parameters:

• mode: SPI_MODE_MASTER or SPI_MODE_SLAVE
• ss_pin: slave-select pin to initialize. The default SS pin varies by port and device, see above.

// Example using SPI in master mode, with the default SS pin:
SPI.begin(SPI_MODE_MASTER);

// Example using SPI1 in slave mode, with D5 as the SS pin
SPI1.begin(SPI_MODE_SLAVE, D5);

// Example using SPI2 in slave mode, with C0 as the SS pin
// (Electron and E-Series only)
SPI2.begin(SPI_MODE_SLAVE, C0);

On Gen 3 devices (Argon, Boron, and Xenon), SPI slave can only be used on SPI1. It is not supported on SPI. The maximum speed is 8 MHz on SPI1.

end()

Disables the SPI bus (leaving pin modes unchanged).

// SYNTAX
SPI.end();

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.end().

setBitOrder()

Sets the order of the bits shifted out of and into the SPI bus, either LSBFIRST (least-significant bit first) or MSBFIRST (most-significant bit first).

// SYNTAX
SPI.setBitOrder(order);

Where, the parameter order can either be LSBFIRST or MSBFIRST.

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.setBitOrder().

setClockSpeed

Sets the SPI clock speed. The value can be specified as a direct value, or as as a value plus a multiplier.

// SYNTAX
SPI.setClockSpeed(value, scale);
SPI.setClockSpeed(frequency);

// EXAMPLE
// Set the clock speed as close to 15MHz (but not over)
SPI.setClockSpeed(15, MHZ);
SPI.setClockSpeed(15000000);

The clock speed cannot be set to any arbitrary value, but is set internally by using a divider (see SPI.setClockDivider()) that gives the highest clock speed not greater than the one specified.

This method can make writing portable code easier, since it specifies the clock speed absolutely, giving comparable results across devices. In contrast, specifying the clock speed using dividers is typically not portable since is dependent upon the system clock speed.

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.setClockSpeed().

Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker SoM) support SPI speeds up to 32 MHz on SPI and 8 MHz on SPI1.

setClockDividerReference

This function aims to ease porting code from other platforms by setting the clock speed that SPI.setClockDivider is relative to.

For example, when porting an Arduino SPI library, each to SPI.setClockDivider() would need to be changed to reflect the system clock speed of the device being used.

This can be avoided by placing a call to SPI.setClockDividerReference() before the other SPI calls.

// setting divider reference

// place this early in the library code
SPI.setClockDividerReference(SPI_CLK_ARDUINO);

// then all following calls to setClockDivider() will give comparable clock speeds
// to running on the Arduino Uno

// sets the clock to as close to 4MHz without going over.
SPI.setClockDivider(SPI_CLK_DIV4);

The default clock divider reference is the system clock.

On Gen 3 devices (Argon, Boron, B-Series SoM, and Tracker SoM), system clock speed is 64 MHz.

On the Gen 2 (Photon, P1, Electron, and E-Series), the system clock speeds are:

• SPI - 60 MHz
• SPI1 - 30 MHz

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.setClockDividerReference().

setClockDivider()

Sets the SPI clock divider relative to the selected clock reference. The available dividers are 2, 4, 8, 16, 32, 64, 128 or 256. The default setting is SPI_CLOCK_DIV4, which sets the SPI clock to one-quarter the frequency of the system clock.

// SYNTAX
SPI.setClockDivider(divider);

Where the parameter, divider can be:

• SPI_CLOCK_DIV2
• SPI_CLOCK_DIV4
• SPI_CLOCK_DIV8
• SPI_CLOCK_DIV16
• SPI_CLOCK_DIV32
• SPI_CLOCK_DIV64
• SPI_CLOCK_DIV128
• SPI_CLOCK_DIV256

The clock reference varies depending on the device.

• On Gen 3 devices (Argon, Boron, B-Series SoM, Tracker SoM), the clock reference is 64 MHz.
• On Gen 2 devices (Photon, P1, Electron, E-Series), the clock reference is 120 MHz.

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.setClockDivider().

setDataMode()

Sets the SPI data mode: that is, clock polarity and phase. See the Wikipedia article on SPI for details.

// SYNTAX
SPI.setDataMode(mode);

Where the parameter, mode can be:

• SPI_MODE0
• SPI_MODE1
• SPI_MODE2
• SPI_MODE3

transfer()

Transfers one byte over the SPI bus, both sending and receiving.

// SYNTAX
SPI.transfer(val);
SPI1.transfer(val);

Where the parameter val, can is the byte to send out over the SPI bus.

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.setDataMode().

transfer() acquires the SPI peripheral lock before sending a byte, blocking other threads from using the selected SPI peripheral during the transmission. If you call transfer in a loop, call beginTransaction() function before the loop and endTransaction() after the loop, to avoid having another thread interrupt your SPI operations.

transfer(void*, void*, size_t, std::function)

For transferring a large number of bytes, this form of transfer() uses DMA to speed up SPI data transfer and at the same time allows you to run code in parallel to the data transmission. The function initializes, configures and enables the DMA peripheral’s channel and stream for the selected SPI peripheral for both outgoing and incoming data and initiates the data transfer. If a user callback function is passed then it will be called after completion of the DMA transfer. This results in asynchronous filling of RX buffer after which the DMA transfer is disabled till the transfer function is called again. If NULL is passed as a callback then the result is synchronous i.e. the function will only return once the DMA transfer is complete.

Note: The SPI protocol is based on a one byte OUT / one byte IN interface. For every byte expected to be received, one (dummy, typically 0x00 or 0xFF) byte must be sent.

// PROTOTYPE
void transfer(const void* tx_buffer, void* rx_buffer, size_t length, wiring_spi_dma_transfercomplete_callback_t user_callback);
typedef void (*wiring_spi_dma_transfercomplete_callback_t)(void);

// SYNTAX
SPI.transfer(tx_buffer, rx_buffer, length, myFunction);

Parameters:

• tx_buffer: array of Tx bytes that is filled by the user before starting the SPI transfer. If NULL, default dummy 0xFF bytes will be clocked out.
• rx_buffer: array of Rx bytes that will be filled by the slave during the SPI transfer. If NULL, the received data will be discarded.
• length: number of data bytes that are to be transferred
• myFunction: user specified function callback to be called after completion of the SPI DMA transfer. It takes no argument and returns nothing, e.g.: void myHandler(). Can be NULL if not using a callback.

NOTE: tx_buffer and rx_buffer sizes MUST be identical (of size length)

Since 0.5.0 When SPI peripheral is configured in slave mode, the transfer will be canceled when the master deselects this slave device. The user application can check the actual number of bytes received/transmitted by calling available().

Note that you must use the same SPI object as used with SPI.begin() so if you used SPI1.begin() also use SPI1.transfer().

If you are using the callback, it is called as an interrupt service routine (ISR) and there are many restrictions when calling from an interrupt context. Specifically for SPI, you cannot SPI.endTransaction() or start another DMA transaction using SPI.transfer().

You should not set the CS pin high from the callback ISR. The callback is called when the DMA transaction is completed, which can be before the data is actually transmitted out of the SPI FIFO.

Thus in practice it's often better to perform your SPI operations from a worker thread instead of chained interrupts if you want asynchronous execution.

Things you should not do from an ISR:

• Any memory allocation or free: new, delete, malloc, free, strdup, etc.
• Any Particle class function like Particle.publish, Particle.subscribe, etc.
• Most API functions, with the exception of pinSetFast, pinResetFast, and analogRead.
• delay or other functions that block.
• Log.info, Log.error, etc.
• sprintf, Serial.printlnf, etc. with a %f (float) value.
• attachInterrupt and detachInterrupt cannot be called within the ISR.
• Mutex locks. This includes SPI transactions and I2C lock and unlock.
• Start an SPI.transaction with DMA.

Since 3.0.0:

On Gen 3 devices with Device OS 3.0.0 and later you can pass byte arrays stored in the program flash in tx_buffer. The nRF52 DMA controller does not support transferring directly out of flash memory, but in Device OS 3.0.0 the data will be copied in chunks to a temporary buffer in RAM automatically. Prior to 3.0.0 you had to do this manually in your code.

transferCancel()

Since 0.5.0:

Aborts the configured DMA transfer and disables the DMA peripheral’s channel and stream for the selected SPI peripheral for both outgoing and incoming data.

Note: The user specified SPI DMA transfer completion function will still be called to indicate the end of DMA transfer. The user application can check the actual number of bytes received/transmitted by calling available().

onSelect()

Since 0.5.0:

Registers a function to be called when the SPI master selects or deselects this slave device by pulling configured slave-select pin low (selected) or high (deselected). This function is called as an interrupt service routine (ISR) so you must be careful about what calls you make from it.

On Gen 3 devices (Argon, Boron, and Xenon), SPI slave can only be used on SPI1.

// SYNTAX
SPI.onSelect(myFunction);

void myFunction(uint8_t state) {
  // called when selected or deselected
}

Parameters: handler: the function to be called when the slave is selected or deselected; this should take a single uint8_t parameter (the current state: 1 - selected, 0 - deselected) and return nothing, e.g.: void myHandler(uint8_t state)

// SPI1 slave example
static uint8_t rx_buffer[64];
static uint8_t tx_buffer[64];
static uint32_t select_state = 0x00;
static uint32_t transfer_state = 0x00;

SerialLogHandler logHandler(LOG_LEVEL_TRACE);

void onTransferFinished() {
    transfer_state = 1;
}

void onSelect(uint8_t state) {
    if (state)
        select_state = state;
}

/* executes once at startup */
void setup() {
    for (int i = 0; i < sizeof(tx_buffer); i++)
      tx_buffer[i] = (uint8_t)i;
    SPI1.onSelect(onSelect);
    SPI1.begin(SPI_MODE_SLAVE, A5);
}

/* executes continuously after setup() runs */
void loop() {
    while (1) {
        while(select_state == 0);
        select_state = 0;

        transfer_state = 0;
        SPI1.transfer(tx_buffer, rx_buffer, sizeof(rx_buffer), onTransferFinished);
        while(transfer_state == 0);
        if (SPI1.available() > 0) {
            Log.dump(LOG_LEVEL_TRACE, rx_buffer, SPI1.available());
            Log.info("Received %d bytes", SPI1.available());
        }
    }
}

On Gen 2 devices, this example can use SPI instead of SPI1. Makes sure you change all of the calls!

Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

available()

Since 0.5.0:

Returns the number of bytes available for reading in the rx_buffer supplied in transfer(). In general, it returns the actual number of bytes received/transmitted during the ongoing or finished DMA transfer.

// SYNTAX
SPI.available();