mbedmicro/mbed — pull request #808 by PrzemekWirkus (2014-12-19 15:57:00+00:00)
Title: Pinology

## Description
This pull requests introduces simple improvements for GPIO HAL functions in mbed SDK.
Improvements introduce:
* new GPIO function: gpio_is_connected(const gpio_t *obj) which can determine if gpio pin is set as NC or connected to h/w pin,
* DigitalIn, DigitalOut, DigitalInOut interfaces gained is_connected() method,
* BusIn, BusOut, BusInOut interfaces gained new operator[n] which works as 'random access iterator to n'th pin in Bus component.
* BusIn, BusOut, BusInOut interfaces gained new function mask() which returns binary mask of connected pins (easy way to filter in runtime Bus' pins set to NC).
* Simple tests added to check if BusOut::operator[unsigned int] is working and if DigitalOut::is_connected() is also correctly returns pin state.

## Rationale
Currently if you want to set proper bit(s) in Bus component you have to use write() method which will set all pins. In case you want to set/clear single pin you need to perform some bit operations and set/clear pin you want.

```c++
BusOut bus(LED1, LED2, LED3);

// Old way: set LED2
int current_mask = bus.read();
current_mask |= 0x02;
bus.write(current_mask);

// New API
bus[1] = 1; // LED1 = 1

// or safer, if you want to check if pin is not in NC state:

if (bus[1].is_connected()) { // We want to make sure bus.pin[1] is not NC pin (we avoid assertion)
bus[1] = 1; // LED1 = 1
}
```
### Bus pin masking
You can get bus pin mask to perform bit-wise operations and see e.g. if groups of pins are connected or not
```c++
BusOut bus(LED1, NC, LED2, NC, LED3);
const int mask bus.mask(); // mask = [ 1, 0, 1, 0, 1, 0, 0, ....]

// We can check which pin in bus is actually connected:
if (mask & 0x04) {
// bus[2] is connected
}
```
### LED blinky example
```c++
BusOut bus_out(LED1, LED2, LED3, LED4);
// Just a quick LED blinking...
for (int i=0; i<4; i++) {
if (bus_out[i].is_connected()) {
bus_out[i] = 1;
}
wait(0.2);
if (bus_out[i].is_connected()) {
bus_out[i] = 0;
}
}
```

### Testing
```
singletest.py -i test_spec.json -M muts_all.json -n MBED_BUSOUT -V
```
Output for supporting test:
```
Building library CMSIS (K22F, GCC_ARM)
Building library MBED (K22F, GCC_ARM)
Building project BUS_OUT (K22F, GCC_ARM)
Executing 'python host_test.py -d G:\ -f "C:\Work\mbed-przemek\build\test\K22F\GCC_ARM\MBED_BUSOUT\bus_out.bin" -p COM93 -t 15 -C 4 -m K22F'
Test::Output::Start
MBED: Instrumentation: "COM93" and disk: "G:\"
HOST: Copy image onto target...
HOST: Initialize serial port...
HOST: Reset target...
{start}}
MBED: BusIn mask: 0xF
MBED: BusIn LED mask: 0xF
MBED: BusOut.bit[0] is connected
MBED: BusOut.bit[1] is connected
MBED: BusOut.bit[2] is connected
MBED: BusOut.bit[3] is connected
MBED: Blinking LEDs...
{{success}}
{{end}}
Test::Output::Finish
TargetTest::K22F::GCC_ARM::MBED_BUSOUT::BusOut [OK] in 7.29 of 15 sec
Test summary:
+--------+--------+-----------+-------------+------------------+--------------------+---------------+-------+
| Result | Target | Toolchain | Test ID | Test Description | Elapsed Time (sec) | Timeout (sec) | Loops |
+--------+--------+-----------+-------------+------------------+--------------------+---------------+-------+
| OK | K22F | GCC_ARM | MBED_BUSOUT | BusOut | 7.29 | 15 | 1/1 |
+--------+--------+-----------+-------------+------------------+--------------------+---------------+-------+
Result: 1 OK

Completed in 7.82 sec
```