System modes

Semi-automatic mode

The semi-automatic mode will not attempt to connect the device to the Cloud automatically, but once you connect it automatically handles reconnection. One common use case for this is checking the battery charge before connecting to cellular on the Boron, B-Series SoM, Electron, and E-Series.

This code checks the battery level, and if low, goes back into sleep mode instead of trying to connect with a low battery, which is likely to fail.

The combination of SEMI_AUTOMATIC and threading enabled is a recommended combination; it's what the Tracker Edge firmware uses.

SYSTEM_MODE(SEMI_AUTOMATIC);
SYSTEM_THREAD(ENABLED);

void setup() {
  float batterySoc = System.batteryCharge();
  if (batterySoc < 5.0) {
    // Battery is very low, go back to sleep immediately
    SystemSleepConfiguration config;
    config.mode(SystemSleepMode::ULTRA_LOW_POWER)
      .duration(30min);
    System.sleep(config);
    return;
  }

  // Do normal things here
  Particle.connect();
}

void loop() {
}

Normally, Device OS automatically handles connecting to the network and cloud and retrying as necessary.

If you manually add a timeout, for example to put the device to sleep to conserve battery when it cannot connect to cellular, you should do so with care.

• Even though a cellular connection can occur in as little as 10 seconds with LTE Cat 1, it can take significantly longer, especially with 3G and 2G. A minimum of 120 seconds is recommended for this reason.
• You must also stay awake trying to connect for at least 5 minutes periodically. The SIM may switch between IMSI when failing to connect, and if you do not try for long enough, it may not cycle through them properly, causing the device to stay stuck on one that can't be used in your location.
• After 10 minutes of failing to connect, Device OS will do a full shutdown of the cellular modem and restart it. This can help clear issues in some cases. It is recommended that you wait at least 11 minutes to be sure this can occur.
• If you do not want to wait 11 minutes for battery life reasons, you should implement a variable backoff scheme were you at least do this periodically, say once every several hours, to be sure it will be done eventually. This will also assure that the 5 minute IMSI cycling time requirement is met.
• The 11 minute shutdown of the cellular modem consists of sending it command to full reset, and also removing the power to the modem. This is more thorough than entering sleep mode, or using the reset button on the device.