Digistump Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== API and Function Reference for the Oak ======

===== Particle API =====

There is a [[https://docs.particle.io/reference/firmware/photon/#cloud-functions|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 [[https://community.particle.io/t/doing-something-wrong-with-particle-publish-subscribe/14926/10|known]] [[https://community.particle.io/t/particle-subscribe-unique-device-id-not-returning-correct-values/18422/5|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 [[https://docs.particle.io/support/troubleshooting/mode-switching/photon/#semi-automatic-mode|Particle guide on mode switching]] for more details.
===== ESP8266 API =====


All of the [[http://esp8266.github.io/Arduino/versions/2.0.0/doc/libraries.html|ESP8266 2.0.0 APIs are available]]

Some ESP8266 libraries that change the WiFi connection settings or state may break your Oak. So be prepared to break out a 3.3v USB to Serial adapter, and follow the recovery instructions to [[https://github.com/digistump/OakRestore|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.

You can get out of SoftAP and back to the user sketch by rebooting the Oak or by connecting to the Oak's AP and sending a post request to 192.168.0.1/connect-ap with a raw body of {"idx":0}

Full list of commands implemented on the Oak are here: [[oak:tutorials:internalurls|Oak Internal URLs]]
Digistump Wiki

User Tools

Site Tools

Page Tools
