Pinology

[PrzemekWirkus]

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 received 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 run-time 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 returning 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.

Currently:

BusOut bus(LED1, LED2, LED3);

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

With this pull request:

BusOut bus(LED1, LED2, LED3);
bus[1] = 1;    // New API, 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
}

DigitalOut pin setup check

You can check if DigitalIn, DigitalOut and DigitalInOut component was initialized with NC (not connected) pin name value:

DigitalOut dout(NC);
bool is_conn = dout.is_connected();    // is_conn == false

DigitalOut dout(LED2);
bool is_conn = dout.is_connected();    // is_conn == true

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:

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

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

[matthewelse]

Looks very nice 👍

[0xc0170]

Why is index declared as unsigned int in operator[](unsigned int index) ?

I can't find an exaplanation for those static dummy members. Why is assert commented out? That missing explanation would answer it.

DigitalIn& BusIn::operator[] (unsigned int index) {
    //MBED_ASSERT(index >= MBED_BUS_SIZE);
    //MBED_ASSERT(_pin[index]);
    if (index >= 16 || _pin[index] == NULL) {
        return din_dummy;
    }
    return *_pin[index];
}

[PrzemekWirkus]

1. Index is unsigned because I do not want to check if index is >=0 in code. I can replace it with signed int and add assertion, runtime check. No problem! Not my call, library maintainer should decide.
2. I can of course uncomment assertions, this is why I left them commented so during code review we can decide if we gonna uncomment them or not use them (remove).
3. Dummy is used because nothing is stopping me from declaring bus as:

BusOut bout(NC, NC);
bout[0] = 1;
int x = bout[0];

and when I access bout[0], a non existing pin. In this case I need to return DigitalOut object (my dummy pin) reference so I can keep semantic with operator I've created.
If I have a BusOut class which will not allow me to create NC pins I would not add dummy object.

[0xc0170]

Thanks , that explains it. What's your preference to 2nd (assertation in operator[])?

[PrzemekWirkus]

0xc0170,
I would uncomment both. This is how I see this works anyway - that's why I left those asserts there.

[PrzemekWirkus]

@0xc0170: Simplified code and removed dummies. Now ASSERT will look after correct indexes and NC pins inside Bus component family.