Firmware Versions

[cpetito]

I am currently at OAK Version 1.0.1.  It appears that some folks had problems with 1.0.2 and I see that the current version is 1.0.5.

Is there a place to find a summary of the features/fixes for the various versions in lieu of looking through the repository at the code changes?

Thanks!

[DrJFM]

There doesn't seem to be any well organized collective details on the firmware changes.  Near as I can tell, besides some bug fixes, much of the effort has gone to making the communication and info transfer between User, the Particle Cloud and the Oak smooth and robust.  One real reason to move to 1.0.5 is that this allows a lot fewer trips to the Oak config app to reset the WiFi communication parameters.  Goal is to allow recovery and/or re-programing of Oak whenever something goes awry.  Your WiFi goes down and your Oak looses connection -- early firmware abandoned the selected WiFi parameters and just waited for a re-configuration.  Particle cloud goes down and no graceful recovery.

From 1.0.2 to 1.0.4, this goal seems to have been corrupted by the behavior of the Particle cloud and the Oak device tended to fall into loops of going online and offline every second or two -- and being unresponsive to any OTA communication.  This got straightened out a lot with 1.0.5. 

With 1.0.5 and the now available OakTerm (http://rawgit.com/kh90909/OakTerm/master/index.html Log in as to Particle login), we have a decent place to move forward.  Error recovery and ability to maintain OTA programming access are fairly solid. For example, from OakTerm, you can switch to config mode and back with your program resuming running.  You can do a reboot of your Oak from OakTerm.  When in config mode, you can access the few direct Oak API links described here: https://digistump.com/wiki/oak/tutorials/internalurls These allow verification of firmware versions, ID etc.  You can re-program from config mode -- either entered this way or via a Pin1 to ground power cycle.

Between 1.0.1 and 1.0.5, at least the Blynk library has been updated.  The firmware releases not only update the Oak core firmware, they come with a host of libraries/program modules that may also be updated.  Using Arduino IDE 1.6.9, you can regress from 1.0.5 to 1.0.1 and hopefully such movement will be maintained.  (Unfortunately, you can also load 1.0.2 or 1.0.3 or 1.0.4 but I would not recommend that unless you really want to learn how to do a Factory Restore over a USB Serial port).

This is a complicated three way system and still being invented on all three legs -- Oak, Particle and the User software -- mixed in with WiFi and the internet. There have been bumps, but I think you can beneficially move your base point to 1.0.5.  Hopefully, newer changes will be better documented as the small team attacking issues at Digistump gets a fairly stable base to move forward from.

In essence, IMHO move to 1.0.5.  Forget about ever loading 1.0.2 to 1.0.4.  You can revert to 1.0.1 from the Arduino IDE 1.6.9 and the Board Manager if you ever feel the need.
You get better recovery from WiFi interruptions, code crashes, Particle software changes and such.  OakTerm provides useful tools in 1.0.5 but not 1.0.1 (see http://digistump.com/board/index.php/topic,2302.msg10960.html#msg10960 for details).  Some third party libraries are updated in Oak firmware downloads or provided in Oak specific versions.

Let others try newer releases and move to them when they are not generating lots of Forum activity for problems.  Or when a feature you need is documented as having been added.
Share what you learn that works well with others here and it all moves forward a bit faster.

Cheers
James

[cpetito]

James,

Thank you for such a complete and informative repsonse!

Carl

[emardee]

We should probably compile a summary page of firmware versions in the Wiki somewhere.

Ideally it would have this sort of info in it:

|| Firmware Version	|| Stable/Beta/Unstable	|| Release Date	|| New Features	|| Bugs Fixed	|| Known Bugs
================	================	================	================	================	================
|| 1.0.0	|| Stable	||	||	||	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------
|| 1.0.1	|| Stable	||	|| Manual Mode	||	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------
|| 1.0.2	|| Unstable	||	|| OakTerm	||	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------
|| 1.0.3	|| Unstable	||	||	||	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------
|| 1.0.4	|| Unstable	||	||	||	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------
|| 1.0.5	|| Stable	||	||	|| Particle Delays Fixed	||
-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------	-----------------------------

It could also have links to release notes instead if some of that info was elsewhere.
Does anyone have the complete set of 0.9.x versions listed, so that we can track them all in the Wiki?

[emardee]

Just spotted that pfeerick has added a firmware versions table to the wiki. Great work!

By way of discussion about that page, I'm now wondering what others think about the known bugs column? Is that info better in the detailed descriptions underneath instead? (clearly nothing in that column yet anyway, so is currently pointless, unless we know of some bugs). I thought by dropping it from the table, it'd leave room for the version numbering instead. eg the v1 - v6 (and presumably now beyond?) type numbering, which would allow for handy cross-referencing back to the 0.9.3 - 1.0.5 numbering.

Also perhaps we could add links to the table back to the firmware on github? Do people think that might be useful?

Mike

[PeterF]

Thanks Mike... I forgot to come back and put the link here to let everyone know.

That sounds like a good idea... better to make the top section a useful quick reference. And referencing the matching OakCore numbering would be handy also, and also indicating that it can be somewhat misleading (ie. The system core that matches 1.0.5 reports as 10 (major version 10, minor 5), so when you look on the wifi config page, you'll see 10, but if you query the internals a bit further, you'll realise it's 10-5 (thus 1.0.5). Links back to the github release page / commits for betas wouldn't be such a bad idea also.

[emardee]

To save the other thread from de-railing... I've brought us back here to discuss the Wiki edits for Firmware.\

I've just posted a major overhaul of the table in the Wiki. Be glad of a second pair of eyes to check it.

[PeterF]

lol... good idea.

I had actually opened the page up to start adding the entries, and couldn't as you had it open. The wiki is nice that way... since it doesn't support concurrent editing, it locks everyone else out of that page until you close it.

I moved the column to be next to the firmware version, added the missing numbers, and also added the missing dates for the firmware versions as i finally realised I could get the dates from the github releases.  I also added a blurb underneath about the difference between the two. Hopefully that makes enough sense to discriminate between the two for the purposes of that page. Let me know what you think anyway, and feel free to make any changes that clear it up more.

Do you like the idea of getting rid of the three right-most columns, leaving it at fw version, system version, status and date. Could then add two more columns which simply have asterisks (so not very wide), for bugfix and new_features...

Still need to do two more pages - one giving the overview of the Oak memory model, and another for disaster recovery (courtesy of kh). And maybe write up one on neo-pixels... as I currently have a Oak running a pixel on my shelf... except I just noticed the battery went flat!

[pkourany]

I would be nice to see any planned (upcoming) release and anticipated fixes and enhancements.

[kh]

You can get a list of the changes between different revisions of a GitHub repository with:

https://github.com/<user>/<repository>/compare/<ref1>...<ref2>

where <user> and <repository> are the names of the GitHub user and repository, and <ref1>, <ref2> are the commit hashes, tags or other references indicating the versions you want to see the changes between. Since the OakCore versions are indicated using the git tags 1.0.0, 1.0.1, etc., you can do the following to see the differences between, for example, 1.0.4 and 1.0.5:

https://github.com/digistump/OakCore/compare/1.0.4...1.0.5

The commit messages shown above the code view give a one line summary of each change, and if there is a "..." at the end of the line, clicking on it will open a more detailed description.

[emardee]

PeterF:  Ah, looks like you are right on the version numbering! (Hope I didn't confuse anyone with my ignorance....)

If you look at kh's link (thanks for that!), you can clearly see how the numbering is incremented:

Code: [Select]

-#define OAK_SYSTEM_VERSION_INTEGER 8
+#define OAK_SYSTEM_VERSION_INTEGER 10
 #define OAK_SYSTEM_VERSION_MAJOR 1
 #define OAK_SYSTEM_VERSION_MINOR 0
-#define OAK_SYSTEM_VERSION_RELEASE 3
+#define OAK_SYSTEM_VERSION_RELEASE 5
 
So 1.0.5 is made up of:
OAK_SYSTEM_VERSION_MAJOR 1  (unchanged)
OAK_SYSTEM_VERSION_MINOR 0   (unchanged)
OAK_SYSTEM_VERSION_RELEASE 5    (changed from 3)

and separately it is also:
OAK_SYSTEM_VERSION_INTEGER=10   (incremented from 8 and has nothing to do with the other version numbers)

What about if we changed those last three columns to one called:
Notes (which could mention new feature, Bug fixes, or key bug)

We could give a link to the github readme file for each version too, which gives more detail on features and bug fixes.

[PeterF]

@emardee: Yup, and if you track that files history, you can see how the version numbers incremented or jumped. I basically just used the commit history for the particle_globals.h file as the only real changes to the file post 1.0.0 were to increment the version number. No worries on that front... as I was saying in the other thread, something I had read somewhere made me think the 10 was actually the MAJOR and MINOR digits (1 & 0)... so me saying that before certainly wouldn't have helped!   

Sounds like a plan. I'm just conscious of making that table too wide... the narrower you can make the table, the less the columns need to shrink and word-wrap. See what you think of it now.

@kh: Thanks for that... I knew there had to be an easier way than randomly clicking on history buttons, etc on github! Makes things much easier knowing there is a simply url that can be used for comparison, especially when it accepts releases as a parameter. 

@pkourany: Can't really do that, as that would require either 1) telepathy or 2) a time machine. Future development stuff will most likely remain topics for discussion on the forum. Best I can offer is that when you look at the github commit history, you can see commits that have been accepted, but not yet rolled into a release. Those will be some of the new things to come in the next firmware release. ATM, that looks like a fix for the tone library, adding the 'LED_BUILTIN' constant, and removing some of the ESP_8266 warnings from libraries / making the Oak libraries more likely to be picked over others.

[emardee]

Good work on the further tidy up of wiki page.

I wonder if the 2nd column (and version discussion underneath) should mention "Version Integer" or "System Version Integer", since they are all called OAK_SYSTEM_VERSION.... just the end is either:
Major
Minor
Release
Integer

I figure using the actual terminology from the code might further reduce ambiguity? (possibly!)

The same argument might apply (in a lesser sense) to where you called it Major.Minor.Revision, but the code calls it Major.Minor.Release

[PeterF]

I guess so... just trying to avoid adding too much info to the mix, as unless you're reading the code, you wouldn't realise it says _INTEGER in the code. And when you do realise/need to know, you'd be looking at the code so it's pretty obvious then. Thinking more of end users than programmers

Oops! I obviously got my Release and Revisions mixed... will fix that up (thanks!). I could have said Patch to be even more confusing, as that is the proper semantic versioning term.

The bolding of the stable versions looks good... do think that is enough, or maybe some dark coding? [eg. dk green for stable, dk red for unstable, dk blue for beta,... something like that]?

[emardee]

I was actually tempted to just turn the beta and unstable ones to a grey shade to slightly increase the difference between them... but couldn't see how to do that. (For a similar reason: that most people won't need to know about betas and unstable versions unless they are advanced users... and if they are advanced users they probably won't be using this list as their reference point!).