ESP32 documentation

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
mattyt
Posts: 140
Joined: Mon Jan 23, 2017 6:39 am

ESP32 documentation

Post by mattyt » Sat Dec 01, 2018 11:32 pm

Hi folks,

With some help (thanks Oliver and Sean!) we've cloned the ESP8266 documentation and renamed it to ESP32:

https://micropython-docs-esp32.readthedocs.io

My goal now is to update that documentation. If anyone would be prepared to help out please let me know - I'd be happy to accept pull requests!

https://github.com/mattytrentini/micropython

For the record, as well as more accurately describing the ESP32 port I'm seriously considering introducing an even simpler Quick Reference that applies to all ports (at least PyBoard/8266/32). This could live under General Documentation for MicroPython. Then the port-specific quick references should only describe differences or features unique to that port (and we should strive to minimise those differences!).

Anyway, any comments, feedback or assistance would be very welcome!

rpr
Posts: 15
Joined: Sat Oct 27, 2018 5:17 pm

Re: ESP32 documentation

Post by rpr » Sun Dec 02, 2018 12:12 am

This is a great start. I'm happy to help. I will take a look to see what areas I can do so. Somewhat of a newbie still.

OutoftheBOTS_
Posts: 449
Joined: Mon Nov 20, 2017 10:18 am

Re: ESP32 documentation

Post by OutoftheBOTS_ » Sun Dec 02, 2018 4:26 am

I am very busy ATM but this is something that I might be able to contribute.

I suggest if someone say once a month posts a reminder on this thread will help remind people.

I assume for someone to help out on the doc they would just branch on github then write what they though on the docs the send a PR???

OutoftheBOTS_
Posts: 449
Joined: Mon Nov 20, 2017 10:18 am

Re: ESP32 documentation

Post by OutoftheBOTS_ » Sun Dec 02, 2018 4:27 am

For the record, as well as more accurately describing the ESP32 port I'm seriously considering introducing an even simpler Quick Reference that applies to all ports (at least PyBoard/8266/32). This could live under General Documentation for MicroPython. Then the port-specific quick references should only describe differences or features unique to that port (and we should strive to minimise those differences!).
This is what Lobo does, he only documents what's different for his port from mainstream.

mattyt
Posts: 140
Joined: Mon Jan 23, 2017 6:39 am

Re: ESP32 documentation

Post by mattyt » Thu Dec 06, 2018 8:53 pm

OutoftheBOTS_ wrote:
Sun Dec 02, 2018 4:26 am
I assume for someone to help out on the doc they would just branch on github then write what they though on the docs the send a PR???
Yep!
Technically: Fork the repository [1], make changes then raise a PR [2].
OutoftheBOTS_ wrote:
Sun Dec 02, 2018 4:26 am
I suggest if someone say once a month posts a reminder on this thread will help remind people.
Can do. Will also post periodic updates. So far we've had a couple of PR's from RPRR (thanks!) who was kind enough to update the Technical Specifications and datasheets and how to write the flash.
I've added the Capacitive Touch interface. Next up I'm keen to update PWM to cover the different ranges (up to 40MHz but with a drop in duty resolution as the freq increases). That feature only appeared yesterday by the way; thanks Damien!

[1] ie make a clone of my micropython repository in your account
[2] on my repository to pick up your changes

hanson.alex
Posts: 1
Joined: Tue Nov 27, 2018 1:50 am

Re: ESP32 documentation

Post by hanson.alex » Fri Dec 07, 2018 5:02 am

I'd like to help with a) esp32 docs and b) general micropython docs. For item b) I agree with @mattyt that micropython needs to have a better quick reference that is more general and describes some of the existing documentation limitations / gotchas.

It seems within the realm of possibilities to create a unified API for all micropython ports. This unified API could be generated automatically using a python script. It could use the code's doc string to check function signatures, flag any that can not be merged automatically, for functions that do not exist they for a given port they could return either NotImplementedError or PortCompatabilityError. Then the documentation generator could look for NotImplementedError and PortCompatabilityError to supplement. Thoughts?

Also, does anyone know if this form supports anytime of markup?

Thanks guys!

mattyt
Posts: 140
Joined: Mon Jan 23, 2017 6:39 am

Re: ESP32 documentation

Post by mattyt » Sat Dec 08, 2018 11:04 pm

I'd like to help with a) esp32 docs and b) general micropython docs.
[/quote]
Great! Every little bit of help is very welcome. :)
hanson.alex wrote:
Fri Dec 07, 2018 5:02 am
It seems within the realm of possibilities to create a unified API for all micropython ports. This unified API could be generated automatically using a python script. It could use the code's doc string to check function signatures, flag any that can not be merged automatically, for functions that do not exist they for a given port they could return either NotImplementedError or PortCompatabilityError. Then the documentation generator could look for NotImplementedError and PortCompatabilityError to supplement. Thoughts?
Yes, I think this would be helpful! Any effort to keep the ports compatible would be useful. I suspect the problem you'll face is encouraging the use of the generator - it seems more typical to start a port by copy 'n' pasting from an existing one...

I've been considering tackling this issue from the other side. For a while I've wanted to create a MicroPython script to run on each port and check that the interfaces are correct. A naive implementation could be so simple as to just check for the presence of method names in each module. Something like:

Code: Select all

all(word in dir(machine.I2C) for word in ['readfrom', 'write'])
It could be built up to produce a diff as to how the api's differ from the canonical definition.

We could also put in some rules so even if we accept that CircuitPython has moved I2C we could check that the methods match.
hanson.alex wrote:
Fri Dec 07, 2018 5:02 am
Also, does anyone know if this form supports anytime of markup?
It does but it's quite an old style. You can discover how to mark up your text by clicking the formatting buttons above the text field when you edit - or refer to one of the guides on formatting with phpBB/BBCode.

Post Reply