Wanted: Porting guide / developer guide

[stijn]

Didn't think about the syncing, that's indeed worth it

[SwimDude0614]

This should be a sticky!

[dhylands]

This should be a sticky!

@rambo started a new thread with a more appropriate title:
http://forum.micropython.org/viewtopic.php?f=2&t=160

[pfalcon]

I hope dhyland's replies were helpful, I'd like to add few philosophic comments.

Reading the source of course gives this info but it's a bit laborious (been doing that for the last few hours).

Paradoxically, writing docs is gazillion times more laborious. Proof? You said that you were doing code studying for few hours then, now (if you're around) have been doing it for few days now. And my humble guess that you already know something. But how many lines of notes you wrote in the process of studying? Well, that's it.

I at the process of my initial studying wrote whole 3 paragraphs: https://github.com/micropython/micropyt ... /Internals . Please be fair: have you read that doc? If yes, then you know how painful is writing docs, because you didn't add anything there. If you didn't, the we come to the next problems with docs - they're pain to write, but it's almost impossible to read them - or at least people don't do it for some reason .

Bottom line:

1. People who want to read docs are in the best position to write them, collaboratively. If every beginner would write 3 paragraphs, after 20 beginners we'd have comprehensive docs.
2. There're plenty of docs around to get you started - there're 41 pages in wiki, 600 posts on forum, dozen of excellent blog-like posts from Kickstarter campaign, etc.
3. If you swallowed some of the info above, and only feel more interested, reading code shouldn't be too hard a task. Helpful hint: besides reading it in "spatial" axis, also try "temporal". Like, find a module of interest to you (it's easy - all modules match "mod*.c"), and run log -p <filename> to see how it was developed over time.
4. General idea of MicroPython is that we write Python, and for Python, a lot of docs exist. MicroPython is different, but spirit is the same. Note that even for CPython, there's no "Porting Guide" or "Developer Guide" (feel free to prove me wrong). There's CPython C API docs for example. uPy's C API is different, but if you know CPython API, you will find only similarities.
5. To get more docs for MicroPython, we need more people to contribute, it's as simple as that. People who contribute to uPy now, went thru points 1-4 above, and mostly concentrate on writing code.

[rambo]

Dhyland was/is helpfull and I appreciate you too.

Paradoxically, writing docs is gazillion times more laborious.

I don't think it's even paradoxically.

I at the process of my initial studying wrote whole 3 paragraphs: https://github.com/micropython/micropyt ... /Internals . Please be fair: have you read that doc?

I did, though definitely did not go on to read the CPython internals at that time. It also was bit useless for me at the time since it just barfs up some (admittedly usefull) details when I was looking for a higher level overview as a starting point.

If yes, then you know how painful is writing docs, because you didn't add anything there. If you didn't, the we come to the next problems with docs - they're pain to write, but it's almost impossible to read them - or at least people don't do it for some reason .

I'll probably start writing something I think is newbie (developer) friendly when I manage to get something actually running under Chibi. https://github.com/HelsinkiHacklab/ledm ... ntation.md is the level I aim for when writing docs, it takes a lot of time as we know. On the other end are the misc notes I make for myself which are basically useless for anyone else.

As for reading: Sometimes they're a bit difficult to find, on the documentation page on the website there could be a few links to the best starting points.

2. There're plenty of docs around to get you started - there're 41 pages in wiki, 600 posts on forum, dozen of excellent blog-like posts from Kickstarter campaign, etc.

And people have no idea where to start with that either, a collection of ten links to the currently most useful posts/wikipages/whatnot on the Documentation page would do wonders.

4. General idea of MicroPython is that we write Python, and for Python, a lot of docs exist. MicroPython is different, but spirit is the same. Note that even for CPython, there's no "Porting Guide" or "Developer Guide" (feel free to prove me wrong). There's CPython C API docs for example. uPy's C API is different, but if you know CPython API, you will find only similarities.

I haven't looked at CPython APIs before, I was thinking that it might be helpful but haven't gotten around to that yet. I would have hoped they'd have some sort of "developer guide" giving a quick overview of where to find which reference docs, design philosophy, which details are more important than others (for which reasons) and explaining the coding standards/conventions everyone should use.

5. To get more docs for MicroPython, we need more people to contribute, it's as simple as that. People who contribute to uPy now, went thru points 1-4 above, and mostly concentrate on writing code.

This is understood and once I start to grok this thing I will try to do something about the documentation situation (unless I'm totally burnt out).

[SwimDude0614]

This should be a sticky!

@rambo started a new thread with a more appropriate title:
http://forum.micropython.org/viewtopic.php?f=2&t=160

Oh, I actually meant because of your very first reply - offering some basic starting pointers. When I said "this should be a sticky" I hadn't yet read all the off-topic stuff about IRC

[kfricke]

I not really able to port µPy onto other MCUs, but I did try to find my way into this topic regardless this fact.

My question is, would it be easier to port it to the STM32F10x family of ST ARM-MCU, when STMicroelectronics finally does publish the STM32Cube library to this chip family as well? From their notes on their website i do understand that they do want to publish this piece of software in Q1 2015. As i can interpret from the µPy codebase, it does heavily rely on this HAL. Is this correct or would it be reasonable to port it to the more limited MCUs based on the other support libraries from ST?

My interest regarding this is based on my interest to use some more MCU-boards with µPy. Especially those, which i own some of: Olimexino STM32 (great price vs. value, fabulous power supply options) and Espruino (better power supply options and neat prototyping area).

Regarding to available resources these two should meet pfalcon's suggestions for reasonable and regular needs.

[Damien]

My question is, would it be easier to port it to the STM32F10x family of ST ARM-MCU, when STMicroelectronics finally does publish the STM32Cube library to this chip family as well?

The stmhal port is tailored to STM32F4xx devices. To get the F1xx working we would have to import the F1xx Cube library into that directory, and then make the HAL layer configurable. It's not difficult, but definitely distracts from working on the F4xx features.

The F1xx devices don't have DFU programming, so you need JTAG or a special bootloader to download the firmware. This adds complexity.

[kfricke]

Ok, thanks for those additional details. Since i personally am not able to implement this i will simply need to wait for the F4 features to get fully implemented.

Regarding that missing DFU mode... iirc i have had to flash my Olimex STM32 with a Espruino firmware, in a way not that much different from DFU mode

[kfricke]

I did just notice that ST has publish STM32Cube for the F1 family of their MCUs.