Pin name spaces

[zolkis]

Hardware pin names are usually marked on the circuit boards, that defines a board namespace for pins.

Operating systems, such as Linux, or Zephyr define a pin name mapping that is consistent across the boards supported by the OS.

There is definitely a use case to support OS pin namespace in implementations.
However, supporting board namespaces is very convenient and lowers the bar for simple programs.

The problem is when these name spaces clash. Since we don't control boards nor operating systems, we can't impose a rule to keep those namespaces disjunct. Therefore we can't use both namespaces in the same time (in general), with or without fallback to the other.

IMHO we have the following clean options:

1. Support only OS (system) pin namespace. Keep pin names completely opaque, and say in the spec that the meaning is defined by the OS documentation.
2. Support both board and system namespaces. The developer can choose the namespace when opening a pin. There is a default namespace, which I suggest to be the board namespace, for developer convenience vs manufacturer convenience. Just look at the board and be (almost) sure the labels will work in this API.

In PR #40 currently option 2 is supported, but it can be changed.

@pfalcon, @grgustaf, @nagineni, @poussa please comment.

[pfalcon]

The problem is when these name spaces clash. Since we don't control boards nor operating systems, we can't impose a rule to keep those namespaces disjunct.

Well, the namespaces are usually pretty distinguishable on their own, though edge cases may happen of course. Board pin identifiers are usually strings, though they can be strings of digits like "10". In Linux (for comparison), pin identifiers are integers. In Zephyr, they're "two-coordinate", a pair of port name (string) and an integer. So, for Zephyr a natural way to identify a pin would be an array like ["GPIO_1", 5]. That's a bit verbose, so in a patch I contributed long time ago to Zephyr.js a dot-separated string was used, like "GPIO_1.5". Now, it's possible that a label on a board would be with a dot, and even that on a board it can be written as GPIO1.5, while Zephyr thinks it's GPIO_1.5. Well, I'd consider it's fair to discount such possibility, by giving preference to one choice over another. My preference would be on OS side ;-).

1. Support only OS (system) pin namespace. Keep pin names completely opaque, and say in the spec that the meaning is defined by the OS documentation.

There's also option 1a:

1a. Support only system namespace on C level. But provide convenience modules, e.g. arduino101_pins , completely on JS level (i.e. written in JS). This would ease maintenance considerably IMHO. Of course, that requires mature enough module system (for example, ability to "freeze" some of the modules as the bytecode into executable, while still accepting a raw source via ashell).

2. Support both board and system namespaces. The developer can choose the namespace when opening a pin. There is a default namespace, which I suggest to be the board namespace, for developer convenience vs manufacturer convenience. Just look at the board and be (almost) sure the labels will work in this API.

That works too. If you don't find an idea of implicit separation robust enough, and there're any issues with implementing mapping on JS level, then just providing explicit means of selecting the namespace is a good choice. I see that #40 says:

introduce support for OS pin namespace (default) and board namespace (backup)

Which would be my preference and opposite of your suggestion above, but if there's anticipation that users will strongly prefer board names, having them as default sounds good.

[zolkis]

Thanks Paul for helping.

Well, the namespaces are usually pretty distinguishable on their own,

That depends on the OS. In Zephyr it's likely not an issue, but on Linux it may be. Anyway, the idea to have 2 (or even more) namespaces is not new: usually the one not using pin mapping is called "raw" pin name, otherwise the default is using the pin mapping.

That works too. If you don't find an idea of implicit separation robust enough, and there're any issues with implementing mapping on JS level, then just providing explicit means of selecting the namespace is a good choice.

Mind you that option 2 involves having an extra property mapping in the GPIO init dict. Okay, it will have a default value, but there were opinions we should get rid of it and use namespace fallback. We shortly discussed this and agreed that we definitely don't want fallback between different namespaces, it would create confusion. Built-in intelligence tends to have limits. Instead, make the choice available to devs. So we have some divergent opinions there.

About which is default - first I have put "system" namespace as the default one, for reasons you also shared. However, when discussed with @nagineni we realized the board namespace is more important for devs with simple programs and the pro guys can always write one more init property and have their use case covered. IOW we prioritize making scripting very easy for the non-professionals: just have the board, and take pin names from there.

So it's not yet decided, but I have recorded your preference for "system" as default pin namespace.

[zolkis]

Discussed with @poussa that for now we stay with Option 2, gather experience and then consider again.
Option 2 has some advantages:

• records a developer choice
• doesn't need to require a module when board namespace is used.

The inconvenience is that for using system namespace one more property needs defining in the init dict.