-
Howdy @Gordon
Great post. The primary goal is to ensure that you are 110% happy with the final inclusions that will be in the Espruino code base that you own. When the ESP8266 port is finished, as I say, the parallel Github repository will be destroyed (after harvesting things like the docs).
Let me try and provide thoughts on your comments and questions.
At a high level, a PRIMARY goal of the project is "do no harm" (just like a doctor). There is a snapshot of the Espruino project here:
https://github.com/esp8266-espruino/esp8266-espurino
This is not a fork but a "sand box" against which all development is progressing. This provides a rock steady base for ESP8266 specific work. Anything you or others may have "in-flight" will not impact ESP8266 specific work. But (I hear you say) ... what about changes that are made by the ESP8266 port to the base Espruino code? The good news is that so far ... those have been minimal AND ... each of those I have submitted to you as changes in a "master" fork which you have accepted.
So ... when the time comes to "merge" the ESP8266 port with the master Espruino code base, my hope is that the ONLY final changes will be the inclusion ESP8266 specific project files that will be delta NEW to the master code base with ... ideally ... ZERO changes to the rest of the code base that is not ESP8266 specific.
There are a couple of MAJOR exceptions to that ... which are to do with the build system. The ESP8266 port will introduce new "board files" and also significant additions to the Makefile.
The thinking is that on merge day ... there will be a "pull request" awaiting you which will add the new ESP8266 source files AND changes to the Makefile ... and once you approve ... we will be done. The changes that I find that are necessary in the core Espruino base ... these have been filtering in to you already for your review and approval.
So what will we loose following this mechanism? The answer is the file change history for the new ESP8266 files that don't yet exist in the master repository ... but since those are net new anyway ... that shouldn't be a problem. The history just now is ... well ... useless to you and me.
For the Wiki documentation ... I am huge on documentation. I don't do anything without writing a story behind it when done :-) ... For me right now, the documentation is easiest for me to capture in Wiki format. The new ESP8266 source files are being liberally commented internally. As for the generated end user docs ... you are 100% correct. When the files are provided for merging, they will be updated to include the docs necessary for "build_docs.py" (is the hope and intent).
I fully agree that a staticmodule of ESP8266WiFi is wrong and will indeed change to making it a library. That is the kind of polish that we need to capture before completion. In the original Proof of Concept, we used a staticmodule and ... so far ... haven't gotten to the stage of reworking to a library.
As for the naming of functions ... I fully agree with you that before completion, we should all get together and review for discrepancies and improvements. Today, I am using the names that are the ones used in the ESP8266 SDK as opposed to ones which have heritage in Espruino ... but by merge day, we should all be consistent.
As for the project as a whole ... once the Proof of Concept proved that Espruino running on ESP8266 was feasible, the next task was to approach it formally with a primary goal of building something that could "slot into" the primary Espruino project. While the naming and the docs are still not where either of us want them to be, the focus just now remains on getting the function working. As you know, the ESP8266 port is still currently broken on the connection callbacks and your post earlier today gave us the knowledge to attempt to rectify that. It is things like that that have my highest priority. I break tasks down into:
- Tasks that we know how to accomplish and merely need to expend time to do them.
- Tasks that we have unknowns upon which include designs, bug fixes and functional testing.
It is the items in category 2 that need most of our attention. The items in 1 can be accommodated before merge day and are merely chores. Items in category 2 are the things that keep me up at night.
The Espruino port to running on the ESP8266 is not complex ... where folks like me are having problems is in understanding how to augment the fantastic Espruino architecture. The core knowledge is locked up in your head and it is only by forum thread exchanges and deep study of the existing code that folks like me can begin to make progress. You have so many irons in the fire, I realize that the ESP8266 port can't commandeer too much of your time so your prompt response on the forum are awesome. If you do have time however, please please don't hesitate to contact me directory (kolban1@kolban.com or skype: neil.kolban) should you have spare time to give us architectural direction and guidance in a more direct fashion.
And ... less there be any doubt. The Espruino code running on the ESP8266 is 99% your current and existing code with the remaining 1% being the ESP8266 specific code ... and that speaks VOLUMES to the quality of what you have created.
Neil
- Tasks that we know how to accomplish and merely need to expend time to do them.
I just got it running too, looks great! It looks like there's a watchdog timer that only gets called from Idle and that resets after 1 sec though? It's probably not a big problem, but worth bearing in mind :)
I notice you've made loads of comments on functions in the Wiki, and have done some comments like this.
If you did them with the comment after (in Markdown) like this instead (like the other functions in Espruino):
Then when
build_docs.py
is run over Espruino, it'll be able to automatically document everything - and crucially all the functions and their documentation are automatically kept in sync, and they come up as tooltips in the Web IDE.Just some other things I noticed:
doc
folder in the Espruino project (or even in some 'Espruino Internals' pages in EspruinoDocs), and kept issuing pull requests then we'd be able to keep everything in sync between your project and the main one. As-is it's going to be a nightmare to pull your documentation back in.ESP8266WiFi
into a library, so you use it likevar wifi = require("esp8266"); wifi.xyz
. It makes things more in sync with the other WiFi modules, and means people could stand a fighting chance of copy/pasting network-related code from other modules - all they'd need to change is the module name..getAPs
that returns[ { ssid, enc, signal_strength, mac_address } ]
. But you've added.getAccessPoints
that returns[ {rssi, channel, authMode, isHidden, ssid} ]
. Instead of.getIP
it's now.getIPInfo
- is there a reason for those changes? It seems crazy to me to make everything different - and it's just going to be far more difficult to change at a later date (especially as people are now starting to use it), and means that nobody can use the existing example code.I don't mean to be negative - it just seems like you're doing a lot of extra work that is going to be hard to put back into normal Espruino... Like rather than contributing to the existing project, you're building your own one.