Where to find the contents of modules and libraries.

[PeterG]

Hello,

I am a Python and microPython newbie but a long-time (47 years) embedded-system designer. I have microPython running on a STM32F4DISC board. I am trying to learn microPython while implementing a particular application. Three questions have arisen, as follows:

1. Where would I find reasonably detailed documentation on the contents and uses of modules and libraries?
2. How can I determine in what module, program or library a particular class or other object is found? and
3. Is there any way to identify the class of an instance of that class via the REPL or by means of a document? This would be helpful when trying to reverse engineer microPython examples.

Any help would be greatly appreciated.

Best regards,

PeterG

[stijn]

1. http://docs.micropython.org/en/latest/ is a good start, this forum might be helpful as well, and then there's the source code.
2. I'd search the documentaion mentioned or the source. E.g. suppose I see a mention of Pin, grepping the ports/stm32 directory points to modmachine.c where the Pin type gets registered. So then you know Pin is part of the machine module.
3. Probably you're looking for the type() function e.g. type('foo') on the REPL prints <class 'str'>

[devnull]

What about:

Code: Select all

help('modules')

[pythoncoder]

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...

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 between the characteristics of the language and those of embedded systems. With your level of experience this is doubtless unnecessary but it can still save time. For example there is a Python debugger on a PC.

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 here. 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 here and the MicroPython utime implementation here - simply search the online docs for utime.

You can determine the class of an instance by issuing instance.__class__. I can't think of a way at the REPL to determine the module which contains the class definition, but dir(module) will produce a list of its contents. So you can interrogate a library:

Code: Select all

>>> 'I2C' in dir(pyb)
True

A useful source of code samples is the test suite.

[PeterG]

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

[HermannSW]

Peter,

I am relatively new to Python/MicroPython as well.

> I have spent hours trying to find out how to do PWM in MP
>
I did need that information as well, but did need 1 minute to find it, just asking Google for "MicroPython PWM" and first hit was link to chapter 7. Pulse Width Modulation in 1.9.4 MicroPython docs.

There are limitations in MicroPython, but I am really impressed by this language, especially that it can run on the bigger (1MB) ESP01s modules. Just completed adding tail(), wc(), cp(), grep() and od() to upysh, and even on those modules booting with 28KB free RAM the needed 6KB allow kind of a real OS experience. The video by Damien George on writing fast and efficient MicroPython is really interesting

Hermann.

P.S:
I started 8 years after you, with 8bit Z80 processor of Sinclair ZX81

P.P.S:
I did post on "where to find what" before:
viewtopic.php?f=2&t=3298&p=31174#p31174

Here you find a complete listing of all MP module contents in just one file (for ESP8266 and ESP32):
https://stamm-wilbrandt.de/en/forum/dif ... -esp32.txt

Searching for "PWM" there immediatly tells you its in "machine" module, searching for "compress" identified "uzlib" and "zlib" modules.

[pythoncoder]

My recommended approach is to learn Python on a PC with CPython 3.4+, Python 3.4 docs and (optionally) pdb. The Unix build of MicroPython is handy for testing MicroPython code but not (in my view) essential for the learning process. MicroPython has no debugger support on any platform; print statements are your friend.

As for the docs I can always find what I want using the search facility on the online docs. However the maintainers welcome GitHub doc submissions: I contributed some content and I'm sure any efforts you make will be equally well received. That is the joy of open source

The relationship between pyb and machine is simple. The pyb library is STM specific. The machine library aims to be cross-platform and is therefore (in rough terms) a subset. If you need to write portable code, use machine. If you want to access the extensive STM specific on-chip hardware, use pyb.

[PeterG]

HermannSW and Peter,

Thank you both for this. I will use that information.

Best regards,

Peter