Documentation

[gepd]

I've been following this proyect for some weeks, but the current state of the documentation is quite inaccurate, for example in the README.md:

Please see the README.md file in the esp32/ subdirectory for details of this port.

At this moment there is not esp32 subdirectory in the current branch, and I don't know what is the official documentation. The docs subdirectory seems to have information about the proyect, but it's mixed with the esp8266 repository.

So it's very hard to start. I've also noted this site http://docs.micropython.org/en/latest/esp8266/ with more usefull and update information, but the same problem it was made for esp8266.

Some days ago I tried to deploy the firmware by my own but I gave up for the same reason.

So I opened this issue is to offer my help and contributte on this matter. I'm preparing a plugin for Sublime Text, it will help to install the firmware from http://micropython.org/download and as there is not support for REPL yet, it will help the user to push and get the current files in the device.

So all the available info will be really apreciate, not only for me, I'm sure it will help to all the people interested in the project.

What do I propose?

Reorganize the current information, update it and if it's necessary write new one. I've note useful information in some issues, it can be copied to the documentation too.

What do you think to put this information in the wiki?

Some questions to start;

What are the features already implemented in this branch?

• [x] machine.freq()
• [x] network / Wifi
• [x] network / Wired
• [ ] network / BLE
• [x] network / ESPNow (soon)
• [ ] OTA
• [ ] SD Update
• [ ] Temp Sensor
• [ ] Hall Sensor
• [ ] SD/SDIO/MMC host
• [x] esp
• [x] time
• [x] machine.Timer
• [x] machine.Pin
• [x] PWM
• [x] ADC
• [x] Software SPI
• [x] Hardware SPI
• [x] I2C
• [x] I2S (soon)
• [ ] RTC
• [ ] EEPROM
• [ ] Deep Sleep
• [ ] Light Sleep
• [ ] Reset Reason
• [ ] ULP
• [x] OneWire
• [ ] webREPL

I've tested the one marked as done, but if I missed something let me know to update the list.

[MrSurly]

Wired LAN (https://github.com/micropython/micropython-esp32/pull/187) is likely to be added soon.

[nickzoic]

Also ESPNow (#197) and I2S (#185) ... I'm hoping to get some more time on this stuff this week.

[dpgeorge]

At this moment there is not esp32 subdirectory in the current branch, and I don't know what is the official documentation

Thanks for pointing this out, the esp32 dir was recently moved to ports/esp32 and I have now updated the README to reflect this change; see a62ef6095b328008746f2eb92e2d1d8e6cefb86f

In 090b6b800b39ee9000a5c759aab0fb13e80a3cc5 I also updated the description of the esp32 port to add more of the features that are now implemented.

[gepd]

List updated.

@dpgeorge Thanks for the update, what do you think about start to organize the info in the wiki? or do you prefer to keep doing it in the docs folder?

[dpgeorge]

what do you think about start to organize the info in the wiki?

Which wiki do you refer to?

[nickzoic]

G'day @gepd,

You're right: the docs for the esp32 port are a little out of date in places. This is one of the reasons why the 'micropython-esp32' repo hasn't be merged back into mainline 'micropython' repo ... it's evolving very fast at this point and not all the APIs are necessarily stable yet.

We do intend to merge it back in to the micropython repo soon though, and pull requests against the docs are very welcome.

It is a bit old school, but I don't see any significant advantage to replacing the 'docs' directory structure with a wiki: better to fix and tidy up what is there and let 'git' do the revision control. This has the advantage that a PR to add a feature X would also update the docs to include feature X ...

[gepd]

@dpgeorge I was refering to the wiki of this repo but @nickzoic clarifys me that repo will be merge back into the micropython repo.

I just have a doubt; I have seen that you are making the esp32 API as compatible as possible with the esp8266 API, how will the docs works in this case?

Will the shared features be in the 'main' directory and the specific/new features in a diffrent folder?

- docs
-shared-documents
-esp8266/specific-documents
-esp32/specific-documents

[dpgeorge]

I have seen that you are making the esp32 API as compatible as possible with the esp8266 API, how will the docs works in this case?

The idea is that all MicroPython ports are as similar as possible, and then there is just one set of docs for all the ports.

[MrSurly]

@dpgeorge I think we do need an ESP32 doc -- just to document the differences. For instance, the HW SPI could list the native pins (those that can run at 40Mhz) for the different SPI HW, Also, how to wire Ethernet, the differences in the TLS implementation, etc.

Updating docs is something that I've been "meaning to do," but I haven't since writing docs is so much fun =^|

Having said that, should we add docs/esp32?

[lifedebug]

hardware SPI? How to use? Thank you!

[gepd]

@lifedebug If I'm not wrong is the same as 8266: http://docs.micropython.org/en/latest/esp8266/esp8266/quickref.html#hardware-spi-bus

But mosi is: GPIO23 and miso GPIO19

[lifedebug]

thank you!but for esp32(micropython),i can't use hw SPI for ILI9341,only has sw SPI ,it is so slow!

[MrSurly]

@lifedebug HW SPI was merged a while ago -- like this:

(from memory -- might be a bit off)

import machine
sck = machine.Pin(10)
mosi = machine.Pin(11)  # Didn't check to see if these pins were actual valid
miso = machine.Pin(12)
spi = machine.SPI(1, baudrate = 100000, sck = sck, mosi = mosi, miso = miso)

That first parameter indicates the hardware SPI unit to use. There are two available in MicroPython for ESP32: 1 and 2. Additionally, if you use the "native" pins for the SPI drivers, you can get ~40MHz, but you can still get pretty good speed using any of the other pins -- it's still hardware.

[lifedebug]

I'll try again later, thanks again

[dpgeorge]

I think we do need an ESP32 doc -- just to document the differences.

For the differences, yes there should be a specific part of the docs dedicated to describing these. Feel free to start writing a docs/esp32/general.rst file :)

[MrSurly]

Feel free to start writing a docs/esp32/general.rst file :)

@dpgeorge

No problem there, except now I have to learn another markdown language, else someone is going to pick apart my PR ;^)

[dpgeorge]

except now I have to learn another markdown language

Just copy and paste existing code :)

[MrSurly]

Just copy and paste existing code :)

Touché, though that's (partiallly) what got me into trouble WRT the wired ethernet PR.

[dpgeorge]

Initial documentation for the esp32 was added upstream in https://github.com/micropython/micropython/commit/69e72954ad4757f8e3faccef6333cb33842ce052