Docs: clarify Trill runtime state persistence

[h4kyu]

Summary

Runtime settings on Trill devices (Trill Square in this case) persist while powered and are not reset between sketches unless explicitly changed or the board is power-cycled. This can cause unexpected behavior when changing sketches (e.g., from RAW-tuned settings to CENTROID without restoring defaults).

Example

The following sketch can be used to reproduce the issue. It continuously prints results of rawDataRead() for the Trill Square to Serial:

#include <Wire.h>
#include "Trill.h"

Trill trillSquare;

// tunables
static const uint8_t  PRESCALER  = 1;
static const uint8_t  SCAN_SPEED = 0;
static const uint8_t  SCAN_RES   = 15;

void printRawData(Trill & trill) {
  while(trillSquare.rawDataAvailable() > 0) {
    int data = trillSquare.rawDataRead();
    if(data < 1000)
      Serial.print(0);
    if(data < 100)
      Serial.print(0);
    if(data < 10)
      Serial.print(0);
    Serial.print(data);
    Serial.print(" ");
  }
  Serial.println("");
}

void setup() {
  Serial.begin(115200);

  if(trillSquare.setup(Trill::TRILL_SQUARE) != 0)
    Serial.println("failed to initialise trill square");
  
  // POINT OF INTEREST-->
  // ***RAW mode runtime settings***
  // delay(10); trillSquare.setPrescaler(PRESCALER);
  // delay(10); trillSquare.setScanSettings(SCAN_SPEED, SCAN_RES);
  // delay(10); trillSquare.setMode(Trill::RAW);

  // ***DIFF mode***
  trillSquare.setMode(Trill::DIFF);
}

void loop() {
  delay(100);
  Serial.println("");
  trillSquare.requestRawData();
  if(trillSquare.rawDataAvailable() > 0) {
    printRawData(trillSquare);
  }
}

I am interfacing with the Trill Square using an Arduino Pro Micro, as outlined in the Bela Trill documentation:

Steps to Reproduce

1. begin with a cold power cycle of the Trill Square and Arduino Micro.
2. Run the sketch with the RAW mode runtime settings commented and DIFF mode uncommented.
3. Take note of Serial output (expected DIFF mode behavior without contact):

0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 
...

4. With the Arduino still powered, run the sketch with the RAW mode runtime settings uncommented and DIFF mode commented.
5. Take note of Serial output (expected RAW mode behavior without contact at PRESCALER = 1 and ScanSettings params):

24012 24326 24735 24310 24036 24872 26996 24588 24752 25759 25349 24472 24884 26012 25089 24842 25256 24223 23753 23540 23524 23996 23903 24196 23877 22798 23282 24111 24618 24270 

24003 24319 24746 24313 24038 24875 26997 24674 24749 25761 25352 24480 24894 26001 25065 24843 25238 24228 23756 23534 23528 23995 23914 24211 23884 22800 23281 24132 24607 24273 
...

6. With the Arduino still powered, run the sketch again with the RAW mode runtime settings commented and DIFF mode uncommented.
7. Take note of Serial output (unexpected behavior):

21024 21282 21668 21282 21035 21763 23620 21544 21640 22557 22135 21429 21793 22758 21919 21746 22171 21198 20770 20606 20588 21004 20906 21186 20921 19966 20371 21103 21540 21239 

21013 21285 21663 21287 21048 21756 23617 21561 21652 22540 22167 21430 21784 22756 21972 21760 22140 21204 20784 20604 20581 20992 20915 21182 20907 19939 20373 21105 21540 21240 
...

8. Without modifying the sketch, power cycle the Arduino and rerun the sketch.
9. Take note of Serial output (back to expected DIFF mode behavior):

0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 
...

Requested Documentation Updates

State persistence callout:
Add a prominent note such as "Trill devices retain mode/prescaler/scan/baseline settings while powered. Power-cycle the board or explicitly set all parameters in setup() when switching sketches."

[giuliomoro]

As we experienced this on early devices, we added a reset command that can be sent for a soft reset on devices with fw 3. This is done routinely as part of setup() in the Linux library, but it's not been ported to the Trill-Arduino version yet. I am unsure it should be there by default as part of begin()/setup() as it slows down boot (reset takes about 500 ms I think) and in an embedded Arduino application it's often unnecessary, as the Arduino will normally be powered up at the same time as the Trill. In general, the Trill-Linux does more things under the hood (e.g.: setting default values) that were not included in the Arduino one, which is more minimal and efficient, for a similar reason (i.e.: defaults are automatically applied on power on).

Where do you recommend we add that prominent note?

[h4kyu]

Thank you for the rapid response! Given the slow boot time, I agree that the soft reset is likely not necessary except for specialized cases where rapid testing between Trill modes is required. It was however an implicit assumption I had made whilst working with Trill-Arduino which caused some confusion on my end.

I believe a good place for the note that is intuitive (as a user) is probably under the Scan settings and/or prescaler setting subsections of the Settings and sensitivity section of documentation, as is highlighted below:

[giuliomoro]

I doubt someone struggling with this issue would necessarily go look for it there. After all, the datasheet already implicitly says that this is the expected behaviour: as long as you don't change a value or reset the device, it will keep its state! The issue is making it clear to those who code it that there is no automatic reset when starting an Arduino sketch.

Maybe it' best to add to each example, if you've set non-default settings on the device since you last turned it on, make sure you power cycle it to ensure consistent behaviour.

What do you think?

[h4kyu]

That's a good point. Although I didn't really catch on to the implicit expected behavior, at least not without carefully reading the docs. Regardless I think your suggestion is great and will do the job!