Thank you for your very comprehensive reply. It is most helpful.
Please see my responses below...
"Greetings to someone who's been coding embedded stuff (slightly) longer than me
You must have started on the 4-bit chips whereas I cut my teeth on the Intel 8080..."
Actually, I started with microprocessors in 1973 with my first MCS6502, made by MOS Technology Inc and later sold to Rockwell. As you may remember, that was the chip that Commodore used in the PET and Apple used in the IIe. It cost $25 and the two manuals were $10 each. One was the TRM and the other was the programming manual. I wrote an assembler for the processor and used both processor and assembler for years. Prior to 1973, I was building programmed machines out of TTL logic inn 4-bit slices, starting in 1971 when I was in second year of my engineering degree.
"I usually recommend that people new to Python learn Python 3.x on a PC first, following a book or online course. This is to make a clear separation .... For example there is a Python debugger on a PC."
The debugger is a great idea. Does anyone develop MP applications in a cross-development environment? It seems to me that developing on a PC (or a Mac in my case) using a cross-compiler and cross-debugger that implement MP features and that emulate the hardware of a pyboard (or STM32F4DISC board in my case). Or perhaps have the cross-development tools issue commands to a shell running on the target board that can execute I/O operations on the pins? This approach would not get the timing right of course, but it would test for the ability to control the relevant pins and other I/O functions.
"Regarding the libraries MicroPython implements a subset of the CPython libraries so a lot can be learned from the official CPython docs. The MicroPython library sourcecode is [url=
https://github.com/micropython/micropython-lib]here[/url]. In many cases there is just a placeholder: not all libraries have been implemented or are even relevant to microcontrollers. So the time library is documented [url=
https://docs.python.org/3.7/library/time.html]here[/url] and the MicroPython [b]utime[/b] implementation [url=
http://docs.micropython.org/en/latest/l ... ight=utime]here[/url] - simply search the online docs for [b]utime[/b]."
I think that an inverse lookup would be valuable, especially by function. I have spent hours trying to find out how to do PWM in MP because not only did I not know what functions to use, but I didn't know in which modules to find them. There are also some interesting duplications, for instance machine.Pin and pyb.Pin seem to be identical. However, "...seem to be..." is a long way from "...are...." in my view. A document that was organized around desired operation ("I want to control Timer 3 to produce PWM, so what functions do I need and where are they found? Ah, yes, the Function Reference Manual has that, look in chapter 4, Timers, section xxx where you find the functions for the generic timers, subsection xxx.yy where you get the functions for Timer 3, and subsubsection xxx.yy.z for PWM on Timer 3") would address that problem and wouldn't be too long.
As I understand it, MP 1.9.4 for STM32 processors is based on the HAL and STM32CubeMX. That tool is excellent for pointing the developer in the right direction, largely at a glance. Could the manual above be built on that? STM32CubeMX generates a .ioc file that contains all the information necessary to determine the particular processor and the I/O devices used and the configuration of those devices including the clock tree, the configuration info required , the middleware, and application software such as USB, FatFS and FreeRTOS as required. That should be enough information to point an on-line manual to the sections that the designer needs. That would greatly reduce the learning curve for uPy.
"You can determine the class of an instance by issuing [b]instance.__class__[/b]. I can't think of a way at the REPL to determine the module which contains the class definition, but [b]dir(module)[/b] will produce a list of its contents. So you can interrogate a library:
[code]>>> 'I2C' in dir(pyb)
True
[/code]"
Thank you. Most helpful.
"A useful source of code samples is [url=
https://github.com/micropython/micropyt ... ster/tests]the test suite[/url].
[/quote]"
A major step in the right direction would be a one-pager that stated just the information in your e-mail. That one-pager should be under the heading of "Getting Started" and should be front and centre for anyone trying to download MP, because it is those people who are getting started.
Thank you again for your help.
Best regards,
Peter Gregson