User Tools

Site Tools


oak:tutorials:api_reference

This is an old revision of the document!


API and Function Reference for the Oak

Particle API

There is a comprehensive user guide over on the Particle.io site, which provides detail descriptions and examples of the different built-in functions that you can use.

The following Particle Cloud Function APIs are working, whilst the remainder are not available for use (yet). Please note that there is a known bug in the Particle.subscribe() function, where specifying a unique device ID to subscribe to has no effect. This is a bug on their side, and the current workaround is the specify the MY_DEVICES constant instead, in order to limit the subscription to just the devices you own, rather than including all public events also.

  • Particle.variable()
  • Particle.function()
  • Particle.publish()
  • Particle.subscribe()
  • Particle.unsubscribe()
  • Particle.connect()
  • Particle.disconnect()
  • Particle.connected()
  • Particle.process()
  • Particle.syncTime() - though time is not yet connected to anything

Controlling connection to Particle

You can use the SYSTEM_MODE() function at the top of your sketch to control your Oak's connection to the Particle cloud, and can choose between three modes (Automatic, Semi-automatic and Manual). The default mode is Automatic, and your Oak will automatically attempt to connect to it's configured Wifi AP, and then try to establish a connection with the Particle cloud. You don't have to specify or do anything to make it do this.

SYSTEM_MODE(SEMI_AUTOMATIC) will prevent the Oak from auto connecting to Particle (or auto attempting) - you'll need to call Particle.connect() to connect. It will however still attempt to establish a wifi connection, but that is all - it will not connect to Particle unless you explicitly tell it to.

SYSTEM_MODE(MANUAL) will prevent the auto connect to Particle AND not automatically check particle for new data each loop when connected. This means you will need to use Particle.process() function reguarly in order maintain the connection to the Particle cloud, but means you have full control over your Oak, and can ensure that time-sensitive code is handled properly.

Check out the Particle guide on mode switching for more details.

ESP8266 API

All of the ESP8266 2.0.0 APIs are available

Some ESP8266 libraries that change the WiFi connection settings or state may break your Oak, or simply prevent your code from compiling (if you are lucky!). Be prepared to break out a 3.3v USB to Serial adapter, and follow the recovery instructions to restore your Oak if you mess with those!

Oak API

uint8_t Oak.getEmptyRom(void) - returns the number of the rom slot that is currently empty (0,4, or 8 - because there are sub slots as well that aren't currently used)

bool Oak.connect(void) - connect to the configured wifi only, not Particle - called automatically on boot as part of the Particle.connect()

bool Oak.connected(void) - returns true if wifi is connected (even if particle is not)

bool Oak.waitForConnection(void) - loops until wifi connects or 15 seconds pass, returns true if connected at end

uint8_t Oak.bootReason(void) - get the reason for the last reboot from the bootloader

void Oak.rebootToUser(void) - reboot to the current user rom

void Oak.rebootToConfig(void) - reboot to the config rom

void Oak.rebootToFallbackUpdater(void) - reboot to the fallback force system updater - do not use

bool Oak.checkRomImage(uint8_t rom_number) - check if the rom image in the slot specified is valid

uint8_t Oak.currentRom(void) - get the slot of the currently running rom

uint8_t Oak.configRom(void) - get the slot of the config rom

uint8_t Oak.userRom(void) - get the slot of the user rom

uint8_t Oak.updateRom(void) - get the slot of the fallback update rom

uint8_t Oak.otaReboot(void) - was the last reboot caused by an attempt to update

SoftAP Protocol

When the Oak is in config mode it exposes an Access Point that the config wizard uses to change settings. This protocol is detailed here: https://github.com/spark/firmware/blob/845a5b489924d6953f966c8b6bb02b915d7f66ae/hal/src/photon/soft-ap.md

Commands are available via http, tcp, and serial.

Full list of commands implemented on the Oak are here: Oak Internal URLs

oak/tutorials/api_reference.1478930622.txt.gz · Last modified: 2016/11/11 22:03 by pfeerick