To answer my own question - you use rt_call_function_n to call a function (I found examples in stm/timer.c)

So would it be good to have:

g = Gpio(pin, dir, mode=PULLUP)
  where: pin is 'PC0' if we are using Damien's approach
  with enumerated values defined in the class for the mode choices above
  (NONE, PULLUP, PULLDOWN, OPEN_DRAIN or OPEN_COLLECTOR)
g = Gpio('PA0', INPUT, mode=PULL_DOWN)

The class could then get these values from the HAL.

IMHO Adc() and Gpio() should both have read/write function name conventions.

When setting up an ADC - you can get to choose the bit depth, or it is defined by the h/w.
If that's in the HAL then you'd be connecting pin (say) 'PB12' to either ADC1 (say) a 16 bit ADC or ADC2 (12 bit).

So you'd want to able to say something like:

a = Adc(pin, adc)
where pin is 'PC0' and adc is something like:
ADC1_12 and ADC2_16 representing the 12 bit ADC and the 16bit ADC available in the h/w.

IMHO we probably want to generalise this further to allow args to go through to the devices.
E.g. when setting up the ADC you may have a param available for sampling speed.
For a Timer - many diff args, same for DMA and PWMs.
If each of these was a 'device' then you could pass these through the *kw args to initialise them in useful ways.

E.g.

a = Adc('PC0', bit_depth=12, samples=200, SH=INTERLEAVED, triggered_by=TIM0)

OR
timer = Timer_device(0, interval=200) # set basic timer behaviour
adc0 = Adc_device(12BIT, sync=timer, sample_hold=CONTINUOUS) # just the ADC
adc1 = Adc_device(12BIT, sync=timer, sample_hold=INTERLEAVED)
a = Adc('PC0', adc=adc0) # assoc the pin with an ADC
b = Adc('PC1', adc=adc1)

Then we can get:

• useful defaults predefined (by setting kw args)
• more direct control over setting up the devices - if user wants to.

On the stm32F405 the hardware supports setting an ADC to trigger when its input passes a threshold set by checking a timer. This generates an interrupt which can fire a DMA action.
IMHO - Its desirable to make this accessible from python.

The STM ADCs have a resolution of 12, 10, 8 or 6 bits, configurable in software. There are 3 ADC blocks, and it looks like they can be individually configured to different resolutions. But, not all ADC channels can be connected to all 3 ADC blocks.

IMHO Adc() and Gpio() should both have read/write function name conventions.

Could elaborate on this? I'm not quite sure what you mean.

@dpgeorge can you point me at the relevant pdf ? I'd like to se if I can tease a useful structure out of it.
@dhylands I just mean that read/ write seems to be the preferred nomenclature rather than get/set.

To elaborate on 6,8,10,12 bits. IMHO A floating point rep will offer the most resolution independence. An integer rep would be more +/- 1 bit accurate but typically a 1 bit error is noise anyway. A byte vs a word seems an unneccesary detail as 1 word is typical size.
So a float would be a good preferred return. If its an int then a full 16 bit int will handle up to 16bit ADCs. Your sign bit may vary.
So maybe:
a = Adc('PC0') and
i = Adc_int('PC0') # can get negative values which need to be 'interpreted'

???

@Neon22 So the API I presented is already read/write. There are no set/get.

For Adc, the read method returns a float, and I presented read_u16 which returns an unsigned 16-bit int (in a python int, which covers the 16-bit range). I see that some platforms in the mbed hal have read_u32 as well.

As for the pins, I think that they should run through the pinmap and we can automatically deal with integer pin numbers and pin numbers like C0 A3, etc.

We could also do the pin mapping as a straight dictionary. Lookup whatever string is passed in and convert to an int. That would allow for board designators (like X1, Y3), or the user could even add arbitrary pinname mappings.

Or we could allow a python pin mapping function to be registered, and we'd pass the pin argument through the python function expecting to get an integer back. The mbed hal uses integers. All of these seem fairly straight-forward to implement, and performance shouldn't be an issue at pin-mapping time.

@dhylands Yes I agree on the pin mapping. The HAL should abstract the string to an int. In fact - I hope you can see I don't disagree with you on anything. My comment was not meant as a criticism.
Your initial post seemed to me to be saying - don't merge this - please comment. Indicating to me that you wanted to see some more perspectives. If my perspective supports yours - this might be good, right ?

As for my wanting to also use the HAL to allow us access to the more in-depth regions of the h/w - which in a naive implementation could be one of the arguments against using python in embedded control (i.e. you need to be able to bit twidlle very deeply so a high level lang is useless. stick with C) - I hope you can see that a keyword arg layer on top of the constructors, and some well designed classes, might allow us a way to do this.
Cheers... :)

@Neon22 Sorry - I'm used to the code review culture at work where every comment is a critique of some sort :)

So its good we agree.

I agree that a kw layer could definitely be benficial. My initial implementation was basically a straight reflection of what's available in the mbed hal API, and then anything we do in addition to that will need to be done carefully, with an eye to portability across platforms (and the kw interface is actually a really good way to support platform specific stuff too - we just need to figure out how to have some platform specific stuff that isn't in the mbed hal).

Oh yeah - so something else I was thinking about was that the python class for gpio could have an attribute which describes the 'modes' which are available ('PULLUP', 'PULLDOWN', 'OPENDRAIN' 'NONE')

Also, I think that to support extra stuff that we want layered on the mbed hal, put which wouldn't necessarily be accepted in the mbed hal git tree, we can create a hal directory inside each target (so have micropython/stm/hal) and put stuff in there, like the supported gpio modes and any associated string to mode mapping, etc.

I see the ADC, Timer, DMA, and numerous other nightmare scenarios are all outlined in the STM32F405 Reference pdf. DM00031020.pdf... Oh joy :)
Luckily there is a Timer app note DM00042534.pdf

I just skimmed through this, so sorry if I missed anything, anyway, you should add pin speeds too, 2MHz, 25MHz, 50MHz and 100MHz, running at full speed might not be needed or even possible for some pins:

Due to the fact that the switch only sinks a limited amount of current (3 mA), the use of
GPIOs PI8 and PC13 to PC15 are restricted: only one I/O at a time can be used as an
output, the speed has to be limited to 2 MHz with a maximum load of 30 pF and these I/Os
must not be used as a current source (e.g. to drive an LED).

Just got to look at this, few comments:

1. As was pointed in the other ticket, there's no need to create Gpio, etc. types dynamically (using mp_obj_new_type()) - doing so wastes dymanic RAM, which is especially precious MCU. These types should be done just the same as any of builtin types. list_type in objlist.c is one of many examples.
2. We definitely should have mp_map_walk() in API, but I'd consider it too heavy-weight way to handle keyword args. It can be optimized out only in -flto mode. Instead, I'd go for making map object structure public and iterating over it explicitly. We'd need to do that anyway to support static maps. (And @dpgeorge confirmed that we want as much stuff static as possible).
3. I'd still call for consideration of standardizing pin addressing based on the actual hardware properties. And actual hardware always have pins organized in ports. Even when it seems that it doesn't, there's still a port - the only one. But it's very rare. And there're hardware with dozens of ports, each having dozens of pins. Do you want to waste your memory with useless defines for thousands of pins, or use random integers? Isn't Gpio(PortK, Pin31) much better?

g = pyb.Gpio(4, dir=pyb.Gpio.DIR_INPUT, mode=pyb.Gpio.PUD_NONE, speed=pyb.Gpio.SPEED_LOW);

That's cool, but you never know what kind of properties vendors can invent for their pins. There's always direction, but anything else indeed can be anything. So, just allow generic "mode" arg with bitmask:

g = pyb.Gpio(PortA, Pin2, dir=pyb.Gpio.DIR_INPUT, mode=pyb.Gpio.PUD_NONE | pyb.Gpio.SPEED_LOW | pyb.Gpio.DRIVE_STRENGTH_LOW|pyb.Gpio.SCHMITT_TRIGGER_OFF|pyb.Gpio.V5_BUFFER_ON);

etc, etc.

@pfalcon

Just got to look at this, few comments:

As was pointed in the other ticket, there's no need to create Gpio, etc. types dynamically (using mp_obj_new_type()) - doing so wastes dymanic RAM, which is especially precious MCU. These types should be done just the same as any of builtin types. list_type in objlist.c is one of many examples.

So the problem that I have is that the constants like DIR_INPUT and DIR_OUTPUT need to be added by the target. I also wanted the target to be able to add additional methods.

The way that I coded it, if you call g = pyb.Gpio(4,speed=pyb.Gpio.SPEED_LOW) then it will wind up calling g.speed(pyb.Gpio.SPEED_LOW) (and the speed method was added by the target, not in the generic code).

I suppose I could add a generic function that the unrecognized kwargs coud be passed to (so that the target can add target-specific features like speed, or schmitt trigger or whatever.

We definitely should have mp_map_walk() in API, but I'd consider it too heavy-weight way to handle keyword args. It can be optimized out only in -flto mode. Instead, I'd go for making map object structure public and iterating over it explicitly. We'd need to do that anyway to support static maps. (And @dpgeorge confirmed that we want as much stuff static as possible).

I didn't want to duplicate that code in each and every hardware abstraction (gio, adc, i2c, etc) which is why I created a routine. Making it inline should make it optimizable.

I'd still call for consideration of standardizing pin addressing based on the actual hardware properties. And actual hardware always have pins organized in ports. Even when it seems that it doesn't, there's still a port - the only one. But it's very rare. And there're hardware with dozens of ports, each having dozens of pins. Do you want to waste your memory with useless defines for thousands of pins, or use random integers? Isn't Gpio(PortK, Pin31) much better?

From a user perspective (the people who will actually be using pyboards), I wouldn't expect specifying ports as K 31 to b better, I'd expect that using the documented identifiers on the board itself (X1, Y3) would be much more natural from the programmers perspective. Myself, I' much rather use direction = pyb.Gpio('Left-Motor-Direction')

The mbed hal uses a simple pin number, and I find pasing around a single thing is much easier than passing around 2 things.

My intention is to allow the user to provide a pin mapping function which will map arbitrary pyhon objects into pin numbers. So you could provide a function which maps a tuple (PortK, 31) into the appopriate pin number, or you could provide a function to map 'X1' or 'K31' or anything else. Then the user has total control over how the pins are named, and internally we'll use the pin numbers that the mbed hal wants.

g = pyb.Gpio(4, dir=pyb.Gpio.DIR_INPUT, mode=pyb.Gpio.PUD_NONE, speed=pyb.Gpio.SPEED_LOW);

That's cool, but you never know what kind of properties vendors can invent for their pins. There's always direction, but anything else indeed can be anything. So, just allow generic "mode" arg with bitmask:

g = pyb.Gpio(PortA, Pin2, dir=pyb.Gpio.DIR_INPUT, mode=pyb.Gpio.PUD_NONE | pyb.Gpio.SPEED_LOW | pyb.Gpio.DRIVE_STRENGTH_LOW|pyb.Gpio.SCHMITT_TRIGGER_OFF|pyb.Gpio.V5_BUFFER_ON);

I was basically allowing the target to add any number of arbitrary extra parameters (through kwargs). In the code I posted, I added the speed parameter as an example.

I'll see what' involved in storing the constants in the type and see if I can convert this back to using a type.

I vote for using the board pin names (X1, Y3, etc). It makes the code more portable and easier for end users. Also the skins are reversible. It's much easier to change all the X's to Y's than try to find what the corresponding MCU port name is for TxD or SDA on the other side. Also the MCU manufacturers are not very good at keeping their pin multiplexing the same between generations, and the next generation pyboard may not even use an ST MCU. That's the advantage of non changing pin names.

So the problem that I have is that the constants like DIR_INPUT and DIR_OUTPUT need to be added by the target. I also wanted the target to be able to add additional methods. The way that I coded it, if you call g = pyb.Gpio(4,speed=pyb.Gpio.SPEED_LOW) then it will wind up calling g.speed(pyb.Gpio.SPEED_LOW) (and the speed method was added by the target, not in the generic code).

IMHO, that's a bit of over-engineering. What we should do is to define good API how GPIO, etc. modules should work. Then each "platform target" can implement its own module in most efficient way. (And module for "mbed platform" will cover bunch of MCU families at once). But even if you want to do that, the Pythonic way to do that is to subclass a base class and add method overrides, etc. You can treat the way you did it as "optimization", but unfortunately, it is not, as it wastes RAM.

We definitely should have mp_map_walk()

I didn't want to duplicate that code in each and every hardware abstraction (gio, adc, i2c, etc) which is why I created a routine. Making it inline should make it optimizable.

Ok, so can you please factor mp_map_walk() out as a separate patch, so we can merge it soon? (And my point was that function you pass to mp_map_walk() is not inlinable per standard, and be done so only with advanced compiler-specific methods).

From a user perspective (the people who will actually be using pyboards), I wouldn't expect specifying ports as K 31 to b better, I'd expect that using the documented identifiers on the board itself (X1, Y3) would be much more natural from the programmers perspective.

But we don't talk "the board", we talk how to support "any board" (all the millions of them) and "any MCU" (all the thousands of them). Once we find good representation which covers "a board", we can support any specific board - easily, truthfully, and efficiently. And that's Python, we can always add any "simple to use" abstraction. But we can't improve efficiency with extra abstractions.

So, the big question we discuss is whether Gpio constructor should accept some scalar value or pair of <port, pin>. I gave bunch of arguments to support explicit ports already, the main being that there are ports in hardware. Here's another one: there're usually number of SPI, I2C, etc. ports (aka blocks) in an MCU. You would instantiate them using myspi = SPI(1), where 1 is of course port number. But for GPIO, you suddenly want to conceal and hide ports. Why??

The mbed hal uses a simple pin number, and I find pasing around a single thing is much easier than passing around 2 things.

You can see what mbed does with it first thing - splits out a port again: https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/targets/hal/TARGET_Freescale/TARGET_K20D5M/gpio_api.c#L31 .
And I agree that it's easier to pass one number instead of two, and PI can be rounded to 3. But that's exactly concealing truth from users - helps in short term, problematic in longer term.

Myself, I' much rather use direction = pyb.Gpio('Left-Motor-Direction')

A string?? But real hardware men don't use strings to do GPIO! Yesterday I grepped google for "micropython" and here's a typical reaction:
http://mybroadband.co.za/vb/showthread.php/577535-Micro-Python-Python-for-microcontrollers?p=11694835&viewfull=1#post11694835

Oh dear.... The bloatware crowd now targeting microcontrollers.

Please don't make that be true. Python doesn't have to be bloat. You of course can use strings or whatever - Python lets you, but let's not force inefficient APIs on everyone (we'll be laughed at).

So, back to you concern, if you want to have X1 for pin, that's oh so easy:

PYB_PORT = 0
X1 = 1

pin = GPIO(PYB_PORT, X1)
# Too long? just stuff 0 instead
pin2 = GPIO(0, X1)

Those initial definitions can (and should) go to a something like board.py, which will be shipped per-board. And we really should start working on Python-source stdlib to accompany interpreter - we can't stuff all those constants in C in flexible manner.

My intention is to allow the user to provide a pin mapping function which will map arbitrary pyhon objects into pin numbers.

There's no need provide nay mapping function, because any mapping capabilities are straight at the user fingertips with Python. What we should care is how efficient and general the most basic representation, and provide simple per-board symbolic pin mappings in a module. Anything else users can do themselves.

I was basically allowing the target to add any number of arbitrary extra parameters (through kwargs)

kwargs are nice, but unfortunately, they're not efficient. If we'll use kwargs everywhere, we can part with the hope to run something in 8K heap (and I personally have high hopes for that, after all, if you do something, you probably want to do it better then how it was done before). So, if there's no strong need for kwargs, it's better not to use them. And IMHO, pin parameters can be reduced to "direction, and everything else" which requires just tuple and so more efficient. (And everything else can be anything - including a dictionary for particular implementation, though most impls will find just int enough).

@pfalcon just trying to be clear.
where: GPIO Port X[0..7] is mapped to physical port PA and pins [1,15,16,17,20,21,22] on the 405
and I2C port 1 is SCL= pin 61, SCA= pin 62.

Please help me to get a handle on it.
Are you saying:
In the C HAL files like mpconfigport.h and stm32f4xx_i2c.c we see:

#elif defined (PYBOARD4)
    #define MICROPY_HW_BOARD_NAME "PYBv4"
    #define MICROPY_HW_GPIO_PORTX          (PortA)
    #define MICROPY_HW_GPIO_PORTY          (PortB)

to define that PortA on the chip is mapped to PortX in the virtual mapping.
And this is where and how we'd see the pins mapped to physical ports because we'd never need to map pins, just ports and indexes in ports. I see how this saves space and doesn't lose flexibility. You'd never need to refer to pin 20 being PortA[4]. No one needs to know.

and in some C file a mapping for all the GPIO modes like:

GPIO_Mode_IN = 1 // currently in stm32f4xx_gpio.h
GPIO_RISING_EDGE  = 1 // made this up
GPIO_Medium_Speed  = 2 // currently in stm32f4xx_gpio.h but not bit position specific

but which may be different for different chipsets and which is exposed up to python also but with a bit more logic so you can define a mode by simply ORing bitfields together. In the example below I manually shifted them but you'd define them as a bit-pattern specific.

and in the python i2c.c file we currently see the mapping for I2C ports 1 and 2 mapped in the code (we'd have to abstract this a bit more somehow for N potential i2c ports on a given chipset).

because in Python we'll have something like:

mode = GPIO_Mode_IN | GPIO_RISING_EDGE | (GPIO_Medium_Speed   << 2)
out1 = Gpio(1, 4, OUTPUT, mode)   # (Port, virtual_pin, In|Out|PWM|.., optional mode  ) (no kw args)
out1.write(value)

s = I2c(1)
s.write_addr(addr, value)

I'm not sure I've got it. Do you mind clarifying it for me please ?

And I have one more specific question - which is a general one really. If we define all these consts, I assume the linker throws away the C defined ones we didn't use, but what about the python exposed ones we didn't use ?

@Neon22: What I'm talking about is higher-level API which will give implementations freedom to have efficient implementation, and provide consistent interface to user, whether the implementation optimized for efficiency or user friendliness. I don't say that each implementation must define ports which corresponds to physical hardware ports - no, it can define just a dummy one, and let users just use 0 in place of it. But it should be there, because next thing users will want is to get most speed from that, and the way to squeeze each last cycle of performance is to follow hardware layout of ports.

In the C HAL files like mpconfigport.h and stm32f4xx_i2c.c we see:

Well, I exactly don't see the code you quote in mpconfigport.h, so I cannot comment on that. But if you mean how that would map to Pyboard, I already hinted, that it can define just one port, and then define constants X1, X2, ... Y1, Y2, ... in its support file (above I called it board.py). How it will map those "virtual" pins to actual hardware pins is up to Pyboard's GPIO implementation code.

and in some C file a mapping for all the GPIO modes like:

I really think we should target for such stuff to be defined in .py files, but otherwise, yes.

In the example below I manually shifted them but you'd define them as a bit-pattern specific.

Yes, you wouldn't need to shift them manually. They will be defined as symbolic constants, that's all. And ideally, they will be just the same values you'd write in hardware GPIO configuration register. Of course, a particular implementation can "map" them in whatever way it wants, the whole point is to not force that "mapping" on each and every implementation, as that wastes cycles.

because in Python we'll have something like:
Here's my edition:

mode = GPIO_Medium_Speed | GPIO_Strong_Drive
out1 = Gpio(0, X4, OUTPUT, mode)
out1.write(value)

s = I2c(I2C1)
s.write_addr(addr, value)

Differences: never use raw numeric values, they usually make no sense, always use symbolic constants. Also, made sure that mode options makes sense for direction=OUTPUT ;-).

If we define all these consts, I assume the linker throws away the C defined ones we didn't use, but what about the python exposed ones we didn't use ?

Well, the constants we don't use now, we'll use later, and someone else uses all the time. If you want to have dynamic language, then you have to keep all stuff around in case it will be needed soon or later. That's the nature of dynamic languages. And if you put those constant in C module and make them available to Python side, it will be the same. Use C++ with templates if you don't like that ;-). But even with dynamical languages, you can try and optimize that - there were already some discussion about.

Abandoning for the time being...

python-on-a-chip has been ported to the mbed(largely?). Maybe it could help ?

https://mbed.org/users/dwhall/notebook/python-on-a-chip/

This issue got a bit out of hand and a bit off topic. Apart from mbed HAL itself, there are 3 main issues raised in the above comments:

1. How to name a pin, how to name a peripheral.
2. Efficiency of constants, identifiers and strings.
3. Design of a general API that supports all boards and MCUs.

Point 3 is really, really difficult. mbed HAL is trying to do this and that's why we were trying to piggy back on top of it. But so far mbed HAL is very simplistic and will not in the near future cover all main features of the STM32F405, let alone of all MCUs and boards.

Let's open separate issues for these individual points.