Go Down

Topic: Arduino-GPIO: Yet Another Fast Digital Pin Library (Read 2158 times) previous topic - next topic

kowalski

Aug 30, 2017, 03:09 pm Last Edit: Sep 16, 2017, 02:56 pm by kowalski
The Arduino-GPIO library has been developed to allow high performance digital pin access. Most access functions are compiled to a single instruction and execute in 1-2 clock cycles. The library functions are more than 10 times faster than the Arduino digital pin functions. In some cases as much as 100 times faster. Additional support classes are available for Shift Register Input/Output, and Software Serial Output. These also demonstrate how the GPIO template class may be used to construct additional libraries (OWI, Software SPI and TWI).

This library supports boards based on SAM3X8E (Arduino Due), ATmega168, ATmega328P (Arduno Uno, Nano, Mini, Lilypad, etc), ATmega32U4 (Arduino Leonardo, Micro, Lilypad USB, etc), ATmega1280, ATmega2560 (Arduino Mega), ATtinyX4 and ATtinyX5 (Arduino Tiny).

The classical Blink example sketch looks like this when using the library.
Code: [Select]

#include "GPIO.h"

GPIO<BOARD::D13> led;

void setup()
{
  led.output();
}

void loop()
{
  led = HIGH;
  delay(1000);
  led = LOW;
  delay(1000);
}


Please see github for more details and the doxygen generated on-line documentation.

Cheers!

Robin2

Interesting.

Do you have a documentation page that lists and explains the function calls for newbies who would not be able to make sense of the source code?

At the moment you have support for a limited range of Arduino boards. An explanation of that the numbers in Board.h mean would be useful for someone who wishes to add support for another board. I am assuming that, for (say) an Attiny1634 all that would be required would be extra stuff in the Board.h file?

By the way "boards.txt" is the name of an important file for defining the different Arduino boards for the IDE. IMHO your name "Board.h" is too similar and humans may get confused even if the compiler won't. What about changing it to ardGpioPins.h

Thanks for sharing.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

kowalski

#2
Aug 30, 2017, 04:24 pm Last Edit: Aug 30, 2017, 04:56 pm by kowalski
The documentation may be found on github and in the source code as Doxygen documentation tags. And by chance all the Arduino ATmega328p and ATmega32u4 based boards are now supported.

The documentation in the Board.h file explains how to construct the pin pointer value. This may be used to add any additional AVR based MCU. Please note that Arduino Mega boards (e.g. ATmega2560 based) are not currently supported as higher port i/o addresses cannot be accessed with a single instruction (i.e. not atomic). This is critical when writing a pin in the ports with higher i/o addresses. Support for this will be added.

Cheers!

Robin2

The documentation in the Board.h file explains how to construct the pin pointer value.
Sorry, I missed that.

Quote
The documentation may be found on github and in the source code as Doxygen documentation tags. And by chance all the Arduino ATmega328p and ATmega32u4 based boards are now supported.
I had looked at your Github page and I had not (and still cannot) see it. Can you post a link?

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

kowalski

The documentation is generated from the source code with doxygen. I have added a doxygen configuration file to make that easier.

Cheers!

Robin2

OK. I think I understand. I was trying to make the point that it would be a good idea (IMHO) to write a documentation file that does not need doxygen so that a newbie who does not know about doxygen can easily use the library.

People who know how to use doxygen probably also know how to do port manipulation without needing a library.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

kowalski

So what is the best practice on documentation? Any good reference, link?

Clean source code that follows style guides and includes documentation tags is easiest to maintain in larger projects. Generating documentation also allows support with automatic generation of UML class diagrams, cross-references, etc. I will include a zip file of the generated HTML documentation on the next tagged release on github.

Cheers!



Robin2

So what is the best practice on documentation? Any good reference, link?
I have been impressed by the documentation for the AccelStepper library and for the TMRh20 version of the RF24 library

Quote
Clean source code that follows style guides and includes documentation tags is easiest to maintain in larger projects. ...
To my mind that means that the developer considers himself more important than his customers - a not uncommon failing in the OpenSource community :)

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

kowalski

#8
Aug 31, 2017, 12:50 am Last Edit: Aug 31, 2017, 12:07 pm by kowalski
Great examples of documentation generated from source code by doxygen. And that is what is available for the GPIO library.

To my mind open-source is about sharing and collaborating with peers. I do not see you as a customer but as a good peer that is willing to take the time to comment and discuss improvements.

Thanks!

Please find the initial documentation on-line

Robin2

Yes. That is going in the right direction.

But I think a newbie would not be clear how this should be used
Code: [Select]
GPIO< PIN >::operator bool  ( )

does it mean that I should write
Code: [Select]
GPIO5::operator_bool() to get the state of pin 5?

I don't think the same ambiguity exists in the AccelStepper documentation.


By the way, I know I am being a PITA. But to my mind good documentation represent 60% of the value of any library.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

kowalski

#10
Aug 31, 2017, 12:20 pm Last Edit: Aug 31, 2017, 12:34 pm by kowalski
Yet another good question. Actually you can find this type of operator definition for the Arduino core Serial class.

Code: [Select]

void setup()
{
  Serial.begin(9600);
  while (!Serial);
  ...
}

The syntax is a way of expressing that, in this case, the GPIO pin can be used as a boolean value in an expression.

Code: [Select]

GPIO<BOARD::D4> pin;

// set the pin to output mode
pin.input();

// some examples of waiting for the pin signal to go high
while (pin == LOW);  
while (pin != HIGH);
while (!pin);

// checking pin state
if (pin == HIGH) ...
if (pin) ...


The GPIO class defines two operators; assignment (operator=) and boolean value (operator bool()). These correspond to the Arduino core digitalWrite() and digitalRead().

Cheers!

Robin2

#11
Aug 31, 2017, 07:06 pm Last Edit: Aug 31, 2017, 07:07 pm by Robin2
The syntax is a way of expressing that, in this case, the GPIO pin can be used as a boolean value in an expression.
I feel you are missing the point I have been trying to make.

You know stuff. Other experts know the same stuff. I don't know the stuff straight off but I reckon I know enough to figure it out.

But it will be double-Dutch to a newbie.

Documentation should be understandable without needing to look up a secondary explanation for the explanation.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

sadr0b0t

loved this example
https://github.com/mikaelpatel/Arduino-GPIO/blob/master/examples/SoftwareSerial/SoftwareSerial.ino

truly elegant replacement for Serial.println

Robin2

loved this example
https://github.com/mikaelpatel/Arduino-GPIO/blob/master/examples/SoftwareSerial/SoftwareSerial.ino

truly elegant replacement for Serial.println
How is that relevant to this Thread?

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

sadr0b0t

How is that relevant to this Thread?

...R
1) This example comes from Arduino-GPIO project repository
2) This thread is about Arduino-GPIO project

Go Up