External pin numbering

Library uniformity on bit/pin manipulation systems

Some micro-controller software environments like the Arduino-IDE provide bit handling functions for port bits

pinMode, digitaRead, digitalWrite

The technique brings advantages for device wiring and some user-friendliness. Device library code usually accepts wiring information by accepting some pin numbers on construction or setup, otherwise one would have to rewrite the library or have a specific version of the library for a specific wiring setup. However this comes with a small performance price, direct port access user coded can combine bit status operations, also pin handler functions generally look for an associated port.

Not that we cannot have inline functions that accept the port and an internal pin (mask) to combine the operations.

//the data&mask cleanup expression is optional, can be just data

inline void portSet(int &port,uint8_t data, uint8_t mask) {port=(port&~mask)|(data&mask);}

Using port functions allows status combination to set multiple bits at once.

It can be implemented as a member function of a port object.

But even so, for libraries that provide pin liberty the status combination is not practical, even if we managed to send all port, mask information.

Arduino IDE environment uses C style table lookup to pin/port maps, this allows to have a sequence numbered pins that looks independent of port.

Some environments like Arduino-Cosa do provide a c++ object to represent a pin, resulting in the same operation.

Either technique can be used with the concept of external pin numbering as well as all other systems that provide software bit/pin manipulation, that is the case of Wiring-PI and many others.

So why do we need external pin numbering?

Just because without them the advantages of libraries with pin liberty, allowing the usage of one device library for any device wiring is lost when one has the device wired behind some other hardware.

That is the case of LyquidCristal library, it uses pin operations but without external pin numbering a new library has to be written to wire the LCD behind shift registers (SPI or I2C).

A small change in the environment allows the creation of extra pins to deliver the information to the device behind I2C, SPI, or other communication port or logic circuitry.

Arduino Virtual Pins is a proposed change to Arduino-IDE that provides extra pin slots to be used with SPI or I2C devices. The technique can be extended for other ports, like Serial, One Wire, etc...

On the environment side the pin manipulation functions translate them as if they were internal pins.

This brings the advantage of using the same libraries, like LiquidCrystal with the I2C or SPI wired device. The library would accept the extra pin numbers and the data translation to the associated port is done outside the library.

This bypass will probably result on an SPI or I2C byte transaction for each bit/pin changed by the library. Unless the library is combining the operations.

Some libraries however do direct port manipulation. For those we provide the same port structure to be manipulated and a function to be called for data dispatch.

The virtual port can be used instead of the internal, but the library must be changed to call the dispatch function.

On some systems one could use memory access interrupts to auto-dispatch the data, however the resource is not available on this platform.

Current version provides 4 extra ports to be mapped for such interfaces, a map setup is required prior to usage, ports must be associated with an interface and eventually some extra information must be provided like CS lines or storage clock pulse on SPI shift registers.

Customization can be done by deriving the translation classes.

On the Arduino IDE environment all arduino/variants maps must be extended to support the extra mappings, it could be done some other way, by catching a pin or port number greater than the available, however the port maps brings extra compatibility with software/libraries that are indexing the tables to get port memory address.

Possible extra functionality:

These are listed as possible because an extra performance impact will be added

• use pin zero to just return, meaning not used. This is somehow useful to signal a CS pin as not used, because sometimes the device is always selected by hardware. This seems useful but would invalidate the use of pin zero as a normal digital pin...
• Use negative pin numbers to reverse the input/output logic, useful for negated logic pins, common in some CS, and all input pins with pull-ups.

having this kind of information encoded on the pin number dispenses extra info on the pin map tables