OakTerm help and discussion

[kh]

A beta version of the cloud serial interface (aka OakTerm) is now available (https://github.com/kh90909/OakTerm), so I've created this thread for discussion and help requests. I'll do my best to answer questions promptly.

However, if you find a bug, please report it on the GitHub issue tracker instead as it's much easier to keep track of there: https://github.com/kh90909/OakTerm/issues.

OakTerm is a terminal app for the Oak that works in a similar fashion to the Arduino Serial Monitor, but data is sent wirelessly via the Particle Cloud rather than the serial port. In place of the Serial.begin(), Serial.print(), Serial.read(), etc. functions in your Arduino sketch, you use the equivalent Particle.* functions instead. It also allows you to see variables exposed by your device (with Particle.variable()), call functions registered with Particle.function(), send Particle Cloud events, and view events sent by your device.

[mikekgr]

Dear kh,
thanks a lot for this very good new for the OAK owners (I am). Because I am not familiar with this OakTerm, could you please give me/us a sketch example with the needed commands in order to use it?

Thanks and Best Regards,
Mike Kranidis

[kh]

Thanks for the suggestion Mike.

I'm working on a full set of example sketches, but in the meantime, here's a basic example:

Code: [Select]

char receive_buffer[255]; // Buffer to store received data

void setup() {
  // Initialize cloud serial
  Particle.begin();
 
  Particle.println("Hello world!");
  Particle.println("Send me data and I will echo it back."); 
}

void loop() {
  // Check if there is any data available to be read
  int avail=Particle.available();

  // Our receive buffer is only 255 bytes long, so limit
  // the number of bytes read to 254, to leave room for
  // a null terminator so that Particle.print() knows
  // where to stop printing
  if(avail>254)
    avail=254;

  // If there is data available
  if(avail>0) {
    // Read it into the buffer
    Particle.readBytes(receive_buffer,avail);
   
    // Add the null terminator
    receive_buffer[avail]=0;
   
    // Print it back to OakTerm
    Particle.print("You just sent: ");
    Particle.print(receive_buffer);
  }
}

If you're familiar with the the Arduino Serial monitor, then you can use OakTerm in a very similar way. Just replace Serial.begin / Serial.read / Serial.print / etc with Particle.begin / Particle.read / Particle.print / etc.

[mikekgr]

Perfect, I will evaluate probably today!
Many thanks Sir.

[PeterF]

I just sacrificed one of my Oaks to horrors of 1.0.2 so I could give OakTerm a try... and it's impressive!

I had issues with the Oak responding after it's first flash with 1.0.2 after previously having 1.0.1 and being pretty stable, so I gave it the steamroller treatment and did a serial update, so it's now running system version 7, and seems to be behaving. I have another Oak running 1.0.1 that can be abused if you have anything you want me to test there...

I mangled the blink sketch to look like the below code snippet, so am getting lots of 'led high/low' messages, and unsurprisingly, hit and miss with variables being registered, but when they do they show up. I've tried the reset, config mode and user mode options, and seems to be doing what it's told just fine.

Code: [Select]

int ledState = 0;

void setup() {
  pinMode(1, OUTPUT);
 
  // Initialize cloud serial
  Particle.begin(); 
 
  Particle.println("Blink sketch has started!");
  Particle.variable("ledState",ledState);
}

void loop() {
  digitalWrite(1, HIGH);   // turn the LED on
  ledState = 1;
  Particle.println("LED High!");
  delay(2000);              // wait
  digitalWrite(1, LOW);    // turn the LED off
  ledState = 0;
  Particle.println("LED Low!");
  delay(2000);              // wait
}


[kh]

Thanks Peter.

When you say it's hit or miss with variables being registered, do you mean that OakTerm doesn't always show the variable value changing? This is to be expected as the Particle Cloud doesn't provide push notifications of variable changes. OakTerm has to poll the variable values, and by default does this once every 10 s.

You can change the poll interval by downloading a local copy of OakTerm (e.g. with "git clone https://github.com/kh90909/OakTerm.git") and changing the interval on this line in "app.js". I don't know if the Particle Cloud imposes a limit on how frequently you can query variable values, but I imagine they wouldn't be very happy with you if you used an interval less than 1 or 2 seconds.

However, if you're looking to provide immediate notifications from your Oak, it's better to use "Particle.print" or send an event with "Particle.publish", because the Particle Cloud provides push notifications for these operations.

[PeterF]

When you say it's hit or miss with variables being registered, do you mean that OakTerm doesn't always show the variable value changing? This is to be expected as the Particle Cloud doesn't provide push notifications of variable changes. OakTerm has to poll the variable values, and by default does this once every 10 s.

This is in reference to the particle cloud even registering the variable, it's not due to a fault on the part of OakTerm. I've had issues with using variables - just not being registered on the cloud, so avoid them generally - I much prefer publish messages as they're pushed and more reliable.

Thanks for the info about changing the poll interval, that explains why there was lag with the variables been updating when the oak did decide to register their existence I suspect there would be a limit... they claim there is one for publish messages, although I have yet to see it actually / lock out.

[PeterF]

On a little further investigation, it looks like it isn't just my setup that is the issue... it is a known issue on the Particle side going back to at least 2014...  where the cloud asks for the list of functions and variables 1.25 seconds after it makes it's connection, and if you device doesn't have the list ready, it isn't updated. It was the topic of discussion again in April, and a manual refresh event is on the cards...

The other issue that was raised was that the return value for variable creation doesn't actually tell you if it was registered on the cloud, only that certain parameters such as length, and number of variables registered have been met. Making it a fairly pointless return value depending on your application...

One possible workaround suggested is to register the variables and function and then drop the particle connection and then reconnect. Code that puts the Oak into semi_automatic or manual connect mode should be more reliable also, as you can then setup cloud variables and functions before starting the cloud connection. This test code I'm using to see if I break OakTerm seems to be registering the variable and function pretty reliably now, instead of 1 in every 10 reboots of the Oak!

Code: [Select]

/*
  OakTermBreaker sketch :)
*/

SYSTEM_MODE(SEMI_AUTOMATIC)

int toggleState = 0;
boolean success = false;

int brewCoffee(String strength)
{
  if (strength.length() != 0)
  {
    Particle.print("You ordered '");
    Particle.print(strength);
    Particle.println("' coffee!");

    return 0;
  }
  else
  {
    Particle.println("Please try placing your order again!");
    return 1;
  }
}

// the setup function runs once when you press reset or power the board
void setup()
{
  /*
     Try to register a variable and a function

     There is no point checking return states as they only indicate if length and type of
     variable are valid, not if the variable or function were actually registered...
     https://community.particle.io/t/registering-variables-problem/21700/13

     This needs to be done ASAP - within 1.25 seconds of the cloud connection for a reliable
     registration, as the 60 second retry is very unreliable, and this is currently no
     way to actively request the variables/functions list to be refreshed....
     https://community.particle.io/t/case-of-the-missing-variables/7462/9
  */
  Particle.variable("toggle", toggleState);
  success = Particle.function("brew", brewCoffee);

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

  Particle.begin(); //the cloud equivalent of Serial.begin()
  Particle.println("OakTermBreaker v0.3 has started!");

  // initialize digital pin 1 as an output.
  pinMode(1, OUTPUT);
}

// the loop function runs over and over again forever
void loop()
{
  digitalWrite(1, HIGH);   // turn the LED on
  Particle.println("LED Blink!");
  delay(500);              // wait
  digitalWrite(1, LOW);    // turn the LED off

  //toggle variable
  if (toggleState == 1)
  {
    toggleState = 0;
  }
  else
  {
    toggleState = 1;
  }

  delay(9500);              // wait
}


[kh]

On a little further investigation, it looks like it isn't just my setup that is the issue... it is a known issue on the Particle side going back to at least 2014...  where the cloud asks for the list of functions and variables 1.25 seconds after it makes it's connection, and if you device doesn't have the list ready, it isn't updated. It was the topic of discussion again in April, and a manual refresh event is on the cards...

...

One possible workaround suggested is to register the variables and function and then drop the particle connection and then reconnect. Code that puts the Oak into semi_automatic or manual connect mode should be more reliable also, as you can then setup cloud variables and functions before starting the cloud connection. This test code I'm using to see if I break OakTerm seems to be registering the variable and function pretty reliably now, instead of 1 in every 10 reboots of the Oak!

Oh, interesting. I haven't run into this issue, but this explains it. Whever I've registered variables, it's always been right at the start of setup(), so they're ready in time. Good to see the workaround works for you.

I saw this Cloud "DESCRIBE" request for the functions and variables when debugging the handshake between the cloud and the device. I wonder if it's possible to extend the Oak firmware to trigger a DESCRIBE, or is this a limitation on the cloud side. I must look for more info on the handshake and messaging protocol.

[PeterF]

I don't know anything about the cloud backend, but it wouldn't suprise me if that was the case. There was a mention in that second thread about

The cloud does support getting updates on that information at runtime, but the firmware doesn't yet volunteer / push that information on change.

making me think that an extra function on the Oak could be used to trigger the pushing of the info to the cloud when the configuration is changed. Especially when it needs to be done dynamically, where exposed functions and variables might change in response to some condition(s).

[kh]

could you please give me/us a sketch example with the needed commands in order to use it?

It took a while, but I now have a full set of example sketches demonstrating how to send and receive data to and from your Oak, send and receive events, view variable values, and call functions. You can view and download them from the OakTerm repository here.

[mikekgr]

Dear Kh,
Thanks a lot for your fine support and the efforts you have put in this project.
When we can do again Oak programming via Arduino (now is impossible due to bugs that found) I will test your examples.

Best Regards,
Mike Kranidis

[DrJFM]

Dear KH,

Thanks for your effort and great tool.  I was using Particle.publish to track how wayward code was progressing, but your terminal is more informative and easier by far.
I blew its mind with a usage it didn't trap for -- left as an issue on Git Hub.

Working well with Arduino IDE Board Manager firmware 1.0.5. -- and so are most other things.  Glad to leave 1.0.2 etc behind me.  I did end up doing a serial restore after my first visit to terminal and hitting one of your buttons (most likely the Config Mode button).  Not sure what firmware I was on, since I was trying to sort that at the time.

For the short term, I am avoiding reset, Config Mode and User Mode buttons.  Can you (here or Git Hub Read Me) expand on which buttons are functional and what there intended course of action is?  Happy to test a bit once I know what is supposed to happen and now that 1.0.5 seems to have solved other issues.

Thanks!
James

[kh]

Hi James,

Thanks. Glad you find it useful.

You should avoid the config mode button if your config mode ROM is older than version 1.0.2. This is because the functionality to receive the config/user/reboot commands was not added until 1.0.2, so when in config mode with a ROM older than this, these buttons will have no effect.

If you do press the config mode button in this situation, you won't be able to return to user mode via the OakTerm buttons. However, you should not need to do a serial update to recover. Simply power cycling the Oak should work, or failing that, going through the softAP setup.

Here are the functions of the buttons:

Refresh	Update the device list, and the variables and functions for the selected device
Send Event	Publishes an event with the ParticleJS publishEvent call
Reboot	Reboot the Oak (similar to power cycling)
Config mode	Reboot to config mode (essentially the same as power cycling with pin 1 grounded)
User mode	Reboot to user mode (whatever sketch you programmed last)
Upload file	Send the contents of a file to the Oak's stdin, which can be read by Particle.read() and similar functions
Send Data	Send the data in the text box to the Oak's stdin, which can be read by Particle.read() and similar functions

I'll update the github readme with this table when I get a chance.

[DrJFM]

Thanks for the quick response.  Most buttons were fairly intuitive sounding, but while playing around with all the firmware releases, I likely did have 1.0.1 or so loaded when I tried the Config button.  Won't happen again. I will be on 1.0.5 or newer for the foreseeable future!

Tried Config to user cycle with 1.0.5 loaded and provides a really easy route to checking the versions etc via the direct api calls to the Oak. 

Where/what is the hosting for the current http://rawgit.com/kh90909/OakTerm/master/index.html?  Permanent? Permanent free? Temporary? 

I hardly ever start the Particle dashboard now and use OakTerm although the Digistump dashboard has some decent widgets.  I have been focused on using Blynk since as a Kickstart backer, I got a lot of Blynk energy units.  Their virtual pins really provide a good mechanism for control.

Again, thanks.

James