Documentation for controlling connectivity on the Spark Core

connectivity.md

By default, the Spark Core connects to the Cloud and processes messages automatically. However there are many cases where a user will want to take control over that connection. The following methods are available to control the connectivity of the Spark Core.

System modes

There are three available system modes: AUTOMATIC, MANUAL_CONNECT, and MANUAL. These modes describe how connectivity is handled.

System modes must be called before the setup() function.

System.mode(AUTOMATIC)

The automatic mode of connectivity provides the default behavior of the Spark Core, which is that:

• When the Core starts up, it automatically tries to connect.
• Once a connection with the Spark Cloud has been established, the user code starts running.
• Messages to and from the Cloud are handled in between runs of the user loop; the user loop automatically alternates with Spark.process().
• Spark.process() is also called during any call of delay() longer than X seconds.
• If the user loop blocks for more than X seconds, the connection to the Cloud will be lost. To prevent this from happening, the user can call Spark.process() manually.
• If the connection to the Cloud is ever lost, the Core will automatically attempt to reconnect. This re-connection will block from X milliseconds up to Y seconds.

System.mode(AUTOMATIC) does not need to be called, because it is the default state; however the user can invoke this method to make the mode explicit.

Usage:

System.mode(AUTOMATIC);

void setup() {
  // This won't be called until the Core is connected
}

void loop() {
  // Neither will this
}

System.mode(MANUAL_CONNECT)

The "manual connect" mode will not attempt to connect the Core to the Cloud automatically. However once the Core is connected to the Cloud (through some user intervention), messages will be processed automatically, as in the automatic process above.

The "manual connect" mode is therefore much like the automatic mode, except:

• When the Core boots up, the user code will begin running immediately.
• When the user calls Spark.connect(), the user code will be blocked, and the Core will attempt to negotiate a connection. This connection will block until either the Core connects to the Cloud or an interrupt is fired that calls Spark.disconnect().

Usage:

System.mode(MANUAL_CONNECT);

void setup() {
  // This is called immediately
}

void loop() {
  if (buttonIsPressed()) {
    Spark.connect();
  } else {
    doOfflineStuff();
  }
}

System.mode(MANUAL)

The "manual" mode puts the Spark Core's connectivity completely in the user's control. This means that the user is responsible for both establishing a connection to the Spark Cloud and handling communications with the Cloud by calling Spark.process() on a regular basis.

When using manual mode:

• The user code will run immediately when the Core is powered on.
• Once the user calls Spark.connect(), the Core will attempt to begin the connection process. TODO: What does the user have to do during this connection?
• Once the Core is connected to the Cloud (Spark.connected() == true), the user must call Spark.process() regularly to handle incoming messages and keep the connection alive. The more frequently Spark.process() is called, the more responsive the Core will be to incoming messages.
• If Spark.process() is called less than every X seconds, the connection with the Cloud will die. It may take a couple of additional calls of Spark.process() for the Core to recognize that the connection has been lost.

Usage:

Spark.mode(MANUAL);

void setup() {
  // This will run automatically
}

void loop() {
  if (buttonIsPressed()) {
    Spark.connect();
  }
  if (Spark.connected()) {
    Spark.process();
    doOtherStuff();
  }
}

System methods

System.factoryReset()

Resets the Core to its factory firmware. Useful for unbricking a bricked Core.

System.bootloader()

Enters bootloader mode (flashing yellow LED), so the Core can be programmed over USB.

System.reset()

Resets the Spark Core, as if the reset button were pressed, or the Core was depowered and repowered.

Network methods

Network.connect()

Attempts to connect to the Wi-Fi network. If there are no credentials stored, this will enter listening mode. If there are credentials stored, this will try the available credentials until connection is successful.

Network.connecting()

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

Network.ready()

This function will return true once the Core 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.

Network.disconnect()

Will disconnect from any connections (including the Cloud), disconnect from the Wi-Fi network, and turn off the Wi-Fi module.

Wi-Fi methods

WiFi.listen()

This will enter listening mode, which opens a Serial connection to get Wi-Fi credentials over USB, and also listens for credentials over Smart Config.

WiFi.listening()

This will return true once WiFi.listen() has been called and will return false once the Core has been given some Wi-Fi credentials to try, either over USB or Smart Config.

WiFi.setCredentials()

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

// 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);

WiFi.hasCredentials()

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

WiFi.clearCredentials()

This will clear all saved credentials from the CC3000's memory.

Spark methods

Spark.connect()

Will attempt to connect to the Spark Cloud. This will automatically activate the Wi-Fi module and attempt to connect to a Wi-Fi network if the Core is not already connected to a network.

Spark.disconnect()

Will disconnect from the Spark Cloud, but keep the connection to the Wi-Fi network. If you would like to completely deactivate the Wi-Fi module, use Network.disconnect().

Spark.connected()

Will return true once the Spark Core is connected to the Cloud, and false when this connection is not established.

Spark.process()

This will automatically process any incoming messages from the Cloud, as well as send pings to keep the connection to the Cloud alive.

If the System.mode() is AUTOMATIC, the user does not need to call Spark.process(); it will happen automatically. If the user puts the Core into MANUAL mode, the user is responsible for calling Spark.process(). The more frequently this function is called, the more responsive the Core will be to incoming messages, the more likely the Cloud connection will stay open, and the less likely that the CC3000's buffer will overrun.