LED_BUILTIN in documentation and variants

[Dennis German]

Who is able to revise the documentation on these pages to
refer to a symbol for the LED_BUILTIN rather than 13 ?

http://arduino.cc/en/Guide/MacOSX#toc6 aka
http://arduino.cc/en/Guide/Windows#toc6 aka
http://arduino.cc/en/Tutorial/Blink
(Others?)

New users have much confusion (I know I did) trying to get Blink example
to run if they try the code on an Arduino ethernet which uses D9 !

Of course it would be helpful if a definition were in all
variants/*/pins_arduino.h files
(not just mega and standard as is currently the case).
But then isn't that the purpose of the variants files in the first place?

And it would be best to have a variants file to the Arduino ethernet.

At a minimum, changing the documentation to use LED_BUILTIN would
cause a compile time error if the symbol is not defined which is better than
attempting to use the incorrect pin!

Thank you for your consideration,
Sincerely,
Dennis German

[Tom Igoe]

We'll add it to the documentation to-do queue.
t.

> --
> You received this message because you are subscribed to the Google Groups "Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[David Mellis]

It might be good to keep the use of "13" for the very basic examples, though, because it seems to work better for introductions to beginners. Also, the LED should be on pin 13 on almost every board.

[Tom Igoe]

My thinking too, Dave.

--
Sent from my Android phone with K-9 Mail. Please excuse my brevity.

[Gmail]

How would you define very basic examples?
I would say that is you use a global variable or define for the led pin  LED_BUILTIN is preferred to 13
Best regards
Jantje

Sent from my Android phone with K-9 Mail. Please excuse my brevity. --

[Tom Igoe]

Dennis, I teach people new to programming and electronics every semester. That's my full-time job.  So if I've forgotten what it's like to be a beginner, or lose empathy for them, I hope my boss will tell me to retire then.

My reasoning for using the number rather than the constant is in fact based on what I see in class. One thing I've found is to minimize the number of concepts into each example. For example, I use no variables on the first day;  just commands.  When it comes to pin numbers, I don't introduce the fact that they can have names until I get across that they have numbers.  Otherwise I get the question, "Wait, pins have names? I thought they just had numbers." 

Once they understand what a command and its parameters are, I introduce variables and constants. 

I would never introduce the ethernet board in an intro class, it's really a more advanced board.  Way too many concepts to introduce to a beginner on that board.

My thinking on the documentation was, rather than modify the example to use the constant in the beginning example for the pin number, we'd modify the page describing the example, and the comments in the example, to say that you can also use the name LED_BUILTIN and the built-in LED on any arduino board will light up.  But I think it's useful to stick with the number in the example, because it offers teachers a chance to explain how pin numbers are used in commands.

t.

On Aug 21, 2013, at 11:24 AM, Dennis German <Dennis...@Real-World-Systems.com> wrote:

Using LED_BUILTIN in the examples
tends  to "abstract" the LED as kind of an object (a good thing).

The "should be" , "almost every board" along with the
chip pin 13 ( verses D13 ) (D9 on the ethernet ! Not present on mini )
is exactly why examples should not include the confusion.
Isn't D13 also used for SCLK (on the Uno?)

With all respect to Tom and Dave, I think you are so well versed in this area as to
forget how things were when you were new to the environment.

Please review my original post and reconsider.
Sincerely,
Dennis German

[David Mellis]

To add on to what Tom said, if you happen to be using a board where the LED isn't on pin 13, it's a nice opportunity to explain how to change the program to use a different pin. For example, I do this when teaching people how to program using an ATtiny.

On a more complex firmware that's mostly intended to be upload as is and used (like the ArduinoISP or StandardFirmata sketches), rather than learned from and modified, I can understand using LED_BUILTIN. But for basic / educational examples, it's good to have the number there.

[Michael Shiloh]

My exact thoughts, as well as my exact experience introducing these
concepts to some 20-30 students every semester.

Michael

--
Michael Shiloh
teachmetomake.com/wordpress
KA6RCQ

Educational Materials coordinator at Arduino.cc
Electronics, Robotics, Digital Fabrication, and Arduino educator
California College of the Arts
San Francisco Art Institute
San Francisco State University

[Bill Perry]

So if you guys are really trying to keep it simple and avoid the pin number vs name concept
then how come you don't create a core function to turn on the "system" LED?

That way it would work for all boards and students can initially focus on other things.

Or maybe turning on/off the LED could be part of a library that offers a collection of very simple functions.

I find it very concerning to have the mind set that having examples/demos in the
IDE that don't work or create compile errors is a good thing.

My guess is that new users would not expect this and assume that they
have done something wrong or that something is wrong with their
board or IDE s/w installation.

I'd much rather see all the examples work and perhaps have
more examples, that slowly walk the user through deeper and deeper concepts.


--- bill

[Cristian Maglie]

In data mercoledì 21 agosto 2013 02:25:27, Dennis German ha scritto:
> Of course it would be helpful if a definition were in all
> variants/*/pins_arduino.h files
> (not just mega and standard as is currently the case).
> But then isn't that the purpose of the variants files in the first place?

Yes it is, I've pushed a fix for that (still missing the Robot_* will be done
asap).

> And it would be best to have a variants file to the Arduino ethernet.

Done also that one.

Thanks.

C

[Cristian Maglie]

Notice also this commit

https://github.com/arduino/Arduino/commit/9b519f2fbc85a3f37fde9aacc73a7e8aea299463

that transforms the LED_BUILTIN from a const variable to a macro as suggested
here:

https://github.com/arduino/Arduino/issues/758

C

[Cristian Maglie]

In data domenica 3 novembre 2013 18:57:37, Cristian Maglie ha scritto:

> that transforms the LED_BUILTIN from a const variable to a macro as

> suggested here:

>

> https://github.com/arduino/Arduino/issues/758

>

> C

Well, thinking on that, currently there is no reason to have only the LED_BUILTIN as a macro, as pointed out here:

https://github.com/arduino/Arduino/issues/758#issuecomment-29158034

so if there are no concerns I'm preparing a patch to change also the other pin constants to a macro.

C

[Cristian Maglie]

> Well, thinking on that, currently there is no reason to have only the

> LED_BUILTIN as a macro, as pointed out here:

>

> https://github.com/arduino/Arduino/issues/758#issuecomment-29158034

>

> so if there are no concerns I'm preparing a patch to change also the other

> pin constants to a macro.

Looking again on this one changing

const int MISO = xxx;

to

#define MISO xxx

have a subtle side effect, for example the following code:

https://github.com/adafruit/Adafruit-MAX31855-library/blob/master/Adafruit_MAX31855.h#L26

declares parameters name as "MISO", but since we #define MISO to something else, the code is screwed up, an produce errors like the following:

sketch_ac_ino:44: error: no matching function for call to 'Adafruit_MAX31855::Adafruit_MAX31855(int, int, int)'

C:\Users\JSweda\Documents\Arduino\libraries\Adafruit_MAX31855/Adafruit_MAX31855.h:24: 

   note: candidates are: Adafruit_MAX31855::Adafruit_MAX31855() 

   note: Adafruit_MAX31855::Adafruit_MAX31855(const Adafruit_MAX31855&)

The same doesn't happen with the const int declaration (since the local name "hides" the global one).

Any idea?

C

[Matthijs Kooijman]

Hey Christian,

> Looking again on this one changing
>
> const int MISO = xxx;
>
> to
>
> #define MISO xxx
>
> have a subtle side effect, for example the following code:
> https://github.com/adafruit/Adafruit-MAX31855-
> library/blob/master/Adafruit_MAX31855.h#L26
> declares parameters name as "MISO", but since we #define MISO to something
> else, the code is screwed up, an produce errors like the following:
> sketch_ac_ino:44: error: no matching function for call to 'Adafruit_MAX31855::Adafruit_MAX31855(int, int, int)'
> C:\Users\JSweda\Documents\Arduino\libraries\Adafruit_MAX31855/Adafruit_MAX31855.h:24:
> note: candidates are: Adafruit_MAX31855::Adafruit_MAX31855()
> note: Adafruit_MAX31855::Adafruit_MAX31855(const Adafruit_MAX31855&)
>
> The same doesn't happen with the const int declaration (since the local name
> "hides" the global one).

Hmm, that's indeed a drawback, especially since it's not unreasonable to
use names like "MISO" for variables etc. If we switch the stuff back to
being a global const, however, we'll lose the ability to use it in a
preprocessor macro, which seems important for writing generic (library)
code to me.

As a compromise, we could perhaps do:

const int MISO = xxx;

#define HAVE_MISO

Since it's unlikely that people will use "HAVE_MISO" (etc.) as a
variable name, this shouldn't cause conflicts, while still allowing
compiling different code depending HAVE_MISO.

For things that were previously already a macro, like LED_BUILTIN (I
think?), we should add a HAVE_LED_BUILTIN define and encourage people to
use it, but not change the LED_BUILTIN itself to a global const now,
perhaps later when libraries have had a chance to adapt from #ifdef
LED_BUILTIN to #ifdef HAVE_LED_BUILTIN.

How does that sound?

Gr.

Matthijs

[Cano]

I suggest we should use macros for MISO, MOSI and similar and people should refrain from using those as their variable names, besides why do you need a variable for MOSI if you already have MOSI defined and there is only one MOSI pin anyway? For devices with multiple SPIs we could define MISO2, MOSI2, ..etc, this way you can also test if there is more SPI devices present

[Randall Routh]

All caps variable names are frequently a bad idea but not uncommon.  What if we went with something like
#define _MISO_ ...
Local variable beginning or ending with underscores is even worse than all caps.

--

[Cristian Maglie]

On Tuesday, January 21, 2014 8:53:11 AM UTC-5, Matthijs Kooijman wrote:
> As a compromise, we could perhaps do:
>
> const int MISO = xxx;
> #define HAVE_MISO
>
> Since it's unlikely that people will use "HAVE_MISO" (etc.) as a
> variable name, this shouldn't cause conflicts, while still allowing
> compiling different code depending HAVE_MISO.
>
> For things that were previously already a macro, like LED_BUILTIN (I
> think?), we should add a HAVE_LED_BUILTIN define and encourage people to
> use it, but not change the LED_BUILTIN itself to a global const now,
> perhaps later when libraries have had a chance to adapt from #ifdef
> LED_BUILTIN to #ifdef HAVE_LED_BUILTIN.
>
> How does that sound?

This sounds like a good B-plan.

To add more facts: I've made a search on all the libraries in adafruit github,
and found that 4 libraries out of >100 will be affected by the same error:

- Adafruit_ILI9340
- Adafruit-Graphic-VFD-Display-Library
- MAX6675-library
- Adafruit-MAX31855-library

all of them are very easily fixable by renaming the parameter in the
constructor.

On Jan 21, 2014 9:21 AM, "Cano" <can...@gmail.com> wrote:
> I suggest we should use macros for MISO, MOSI and similar and people
> should refrain from using those as their variable names, besides why do
> you need a variable for MOSI if you already have MOSI defined and there
> is only one MOSI pin anyway? For devices with multiple SPIs we could
> define MISO2, MOSI2, ..etc, this way you can also test if there is more
> SPI devices present

I agree with you, but we should have an idea about how many projects would be
affected by this change, because what happens is that: user upgrades the IDE ->
his project breaks. This may be acceptable or not, it dipends how much impact
on the user base, and this makes me uncertain if we should keep the change or
not (or eventually adopt it in the 1.5.x series only).

In data martedì 21 gennaio 2014 17:27:57, Randall Routh ha scritto:
> All caps variable names are frequently a bad idea but not uncommon. What
> if we went with something like
> #define _MISO_ ...
> Local variable beginning or ending with underscores is even worse than all
> caps.

I likely avoid changing the constants name in such exotic way.

C

[Matthijs Kooijman]

Hey Christian,

> On Jan 21, 2014 9:21 AM, "Cano" <can...@gmail.com> wrote:
> > I suggest we should use macros for MISO, MOSI and similar and people
> > should refrain from using those as their variable names, besides why do
> > you need a variable for MOSI if you already have MOSI defined and there
> > is only one MOSI pin anyway? For devices with multiple SPIs we could
> > define MISO2, MOSI2, ..etc, this way you can also test if there is more
> > SPI devices present
>
> I agree with you, but we should have an idea about how many projects would be
> affected by this change, because what happens is that: user upgrades the IDE ->
> his project breaks. This may be acceptable or not, it dipends how much impact
> on the user base, and this makes me uncertain if we should keep the change or
> not (or eventually adopt it in the 1.5.x series only).

MOSI and MISO are probably names that won't be often used (unless you
implement some kind of software SPI), but I'd expect the SS name to be
more common (since every SPI device will have it's own SS pin, so more
chance for problems).

The problem is of course more general: If we later add more special
pins for new hardware and we've decided to use #defines, then each pin
name we choose again has the potential to create problems with existing
libraries.

> In data martedì 21 gennaio 2014 17:27:57, Randall Routh ha scritto:
> > All caps variable names are frequently a bad idea but not uncommon. What
> > if we went with something like
> > #define _MISO_ ...
> > Local variable beginning or ending with underscores is even worse than all
> > caps.
>
> I likely avoid changing the constants name in such exotic way.

Agreed.

Gr.

Matthijs

[Cristian Maglie]

In data martedì 21 gennaio 2014 14:53:11, Matthijs Kooijman ha scritto:
> Hmm, that's indeed a drawback, especially since it's not unreasonable to
> use names like "MISO" for variables etc. If we switch the stuff back to
> being a global const, however, we'll lose the ability to use it in a
> preprocessor macro, which seems important for writing generic (library)
> code to me.
>
> As a compromise, we could perhaps do:
>
> const int MISO = xxx;
> #define HAVE_MISO
>
> Since it's unlikely that people will use "HAVE_MISO" (etc.) as a
> variable name, this shouldn't cause conflicts, while still allowing
> compiling different code depending HAVE_MISO.

Thinking on this a bit more, doing this way would mean that we should define
HAVE_xxx for each pin in the variant file, on boards with a lot of pins this
means defining a lot of HAVE_xxxx, where many of them would probably be never
used.

Instead, what about grouping them in "devices" like:

static const uint8_t SS = 10;
static const uint8_t MOSI = 11;
static const uint8_t MISO = 12;
static const uint8_t SCK = 13;
#define HAVE_SPI

This way we can check the existence of a bunch of pins under the same define
HAVE_SPI (that seems also more useful to me).

Looking at the current variants the only other device worth mentioning is the
I2C, it will look like:

static const uint8_t SDA = 18;
static const uint8_t SCL = 19;
#define HAVE_I2C

what do you think?
C

[Matthijs Kooijman]

Hey Christian,

> > As a compromise, we could perhaps do:
> >
> > const int MISO = xxx;
> > #define HAVE_MISO
> >
> > Since it's unlikely that people will use "HAVE_MISO" (etc.) as a
> > variable name, this shouldn't cause conflicts, while still allowing
> > compiling different code depending HAVE_MISO.
>
> Thinking on this a bit more, doing this way would mean that we should define
> HAVE_xxx for each pin in the variant file, on boards with a lot of pins this
> means defining a lot of HAVE_xxxx, where many of them would probably be never
> used.

Doesn't really hurt to have unused defines, though? I don't even think
having hundreds of them will noticably slow down the compilation. It'll
make the pins_arduino.h file a bit more verbose, though.

> Instead, what about grouping them in "devices" like:
>
> static const uint8_t SS = 10;
> static const uint8_t MOSI = 11;
> static const uint8_t MISO = 12;
> static const uint8_t SCK = 13;
> #define HAVE_SPI

I guess that could work. That means that we guarantee that:
- If HAVE_SPI is defined, the SS, MOSI, MISO and SCK constants are
available.
- If HAVE_SPI is not defined, none of SS, MOSI, MISO and SCK is
available.

I'm wondering if there might ever be a board that has SPI, but not all
of the pins, or does not have SPI but still has pins named like that?
The only thing I can imagine is that a board has SPI, but not all of the
SPI pins are also available as general purpose digital pins, meaning we
can't define the pin number constants.

Also, the presence of an "SS" pin is pretty AVR specific: it's strictly
not related to the SPI master interface at all, only to the SPI slave
interface.

I have the feeling that taking this shortcut might just bite us on the
long run, especially due to hardware configurations we don't know about.
So, doing explicit HAVE_ macros for every pin seems right, even though
it's quite verbose...


Were you considering converting the A0 etc. defines to constants as
well? This would be good for consistency, but would also break backwards
compatibility. Perhaps we should put this on the list for 2.0 or
something? Then we should recommend users to switch from
#ifdef A3
to either
#ifdef HAVE_A3
or
#if NUM_ANALOG_INPUTS > 4
depending on wether we want to expose HAVE_A3 macros.

It does seem to me that checking NUM_ANALOG_INPUTS might not work: there
is no guarantee that all analog inputs are also available as digital
ports (there are AVR chips already that have analog inputs that don't
have a digital input equivalent).


Gr.

Matthijs

[Cristian Maglie]

Hi Matthijs !

> > Instead, what about grouping them in "devices" like:
> >
> > static const uint8_t SS = 10;
> > static const uint8_t MOSI = 11;
> > static const uint8_t MISO = 12;
> > static const uint8_t SCK = 13;
> > #define HAVE_SPI
>
> I guess that could work. That means that we guarantee that:
> - If HAVE_SPI is defined, the SS, MOSI, MISO and SCK constants are
> available.
> - If HAVE_SPI is not defined, none of SS, MOSI, MISO and SCK is
> available.

yes, that was the idea.

Surely there are drawbacks, you mentioned:
- the SS pin that may be non present or may be more than one
- MISO/MOSI/SCK may not be enumerated digital pins
- a pin named SS/MISO/MOSI/SCK that is not related to an SPI device
all these cases are hardware-specific (you must eventually handle them on a
per-processor basis in your library) while the goal of variant files is to
reduce hardware-specific dependendecies.

What problem are we trying to solve with those defines? are we providing a way
to check if a particular pin XYZ exists/is mapped? Imagine a device that have
a MISO pin that is not an SPI device but something else, how checking
"HAVE_MISO" helps on that?

So, don't misunderstand me, I'm perfectly fine using HAVE_xxx pin defines if
needed, but I'd really like to see some use case before, is not a problem for
the compiler of course, but I likely avoid clobbering the variant file with a
lot of defines (and forcing 3rd party board developers to do the same) if
possible.

Lauzus mentioned this use case:

https://github.com/felis/USB_Host_Shield_2.0/blob/82c52542cc522982b026bf7f6cdd9059e5064d4a/usbhost.h#L45-
L53

that seems to fit well under the single HAVE_SPI define.

There are some other use cases that may, instead, benefit from having the
HAVE_xxxx pins defined?

> Were you considering converting the A0 etc. defines to constants as
> well? This would be good for consistency, but would also break backwards
> compatibility.

In the current release (1.5.5 and 1.0.5), A0 A1 ... etc. are already
constants, so there is no backward compatibility problem:

https://github.com/arduino/Arduino/blob/1.5.5/hardware/arduino/avr/variants/leonardo/pins_arduino.h#L114

> It does seem to me that checking NUM_ANALOG_INPUTS might not work: there
> is no guarantee that all analog inputs are also available as digital
> ports (there are AVR chips already that have analog inputs that don't
> have a digital input equivalent).

This is really peculiar, maybe we can solve this also with a constant
NOT_A_PIN set to -1 but, again, which use cases are we trying to cover here?

C

[Matthijs Kooijman]

Hi Christian,

> What problem are we trying to solve with those defines? are we providing a way
> to check if a particular pin XYZ exists/is mapped? Imagine a device that have
> a MISO pin that is not an SPI device but something else, how checking
> "HAVE_MISO" helps on that?
>
> So, don't misunderstand me, I'm perfectly fine using HAVE_xxx pin defines if
> needed, but I'd really like to see some use case before, is not a problem for
> the compiler of course, but I likely avoid clobbering the variant file with a
> lot of defines (and forcing 3rd party board developers to do the same) if
> possible.
>
> Lauzus mentioned this use case:
>
> https://github.com/felis/USB_Host_Shield_2.0/blob/82c52542cc522982b026bf7f6cdd9059e5064d4a/usbhost.h#L45-
> L53
>
> that seems to fit well under the single HAVE_SPI define.

I'd even say that HAVE_SPI helps more than separate HAVE_MISO etc.
defines for this case, so perhaps we should define them both?

> There are some other use cases that may, instead, benefit from having the
> HAVE_xxxx pins defined?

I can't think of anything off-hand for the SPI or I2C pin names.
However, looking at for example at the Robot variant files, there are a
lot more special purpose named pins. Having HAVE_xxx constants for those
might be helpful if new versions of those boards with more or less pins
would be released.

However, if we wait with adding those HAVE_ constants until they're
positively useful, then a library can't reliably use them and still
support older IDE versions, which is a reason to include them now.

Ideally, you'd use preprocessor macro to both define the constant and
the HAVE_xxx macro to reduce clutter, but it seems that it's impossible
to define a macro within a macro, so that won't fly unfortunately...

> > Were you considering converting the A0 etc. defines to constants as
> > well? This would be good for consistency, but would also break backwards
> > compatibility.
>
> In the current release (1.5.5 and 1.0.5), A0 A1 ... etc. are already
> constants, so there is no backward compatibility problem:
>
> https://github.com/arduino/Arduino/blob/1.5.5/hardware/arduino/avr/variants/leonardo/pins_arduino.h#L114

Oh, I was looking at an older third-party variant file I think. Ok, not
a problem, then :-)

> > It does seem to me that checking NUM_ANALOG_INPUTS might not work: there
> > is no guarantee that all analog inputs are also available as digital
> > ports (there are AVR chips already that have analog inputs that don't
> > have a digital input equivalent).
>
> This is really peculiar, maybe we can solve this also with a constant
> NOT_A_PIN set to -1 but, again, which use cases are we trying to cover here?

That won't work right now, since NOT_A_PIN is 0 and is thus unsuited to
be used as an invalid pin number (I've stumbled across this before):

https://github.com/arduino/Arduino/blob/1.5.5/hardware/arduino/avr/cores/arduino/Arduino.h#L151

Seems NOT_A_PIN is to be used in the context of a port number, which
start at 1.

If we would change it to -1, or add a new constant, I guess we could do
this (though I'm afraid it might only add confusion, especially since
something like digitalRead(Ax) will then succesfully compile, but do an
out-of-bounds read id we don't add bounds checks everywhere...


Gr.

Matthijs

[Matthijs Kooijman]

Hey Christian,

just something I realized while reading stdbool.h: Instead of defining
HAVE_MISO, we could also define MISO to itself. So:

const uint8_t MISO = 13;
#define MISO MISO

This will allow sketches to still test #ifdef MISO, but not cause
problems with variables named MISO.

This makes things slightly less ugly than the HAVE_MISO approach, but
perhaps also slightly more confusing. Furthermore, it doesn't solve the
fact that we still need two lines per pin in pins_arduino.h....

Gr.

Matthijs

[Bill Perry]

I know that  this is a really old thread, but nothing seems to happened related to this.
IMO, an easy solution is the approach below which is to create the define that maps to the const int variable name
i.e. #define FOO FOO

While it does duplicate each pin definition that uses this, it is very clean and simple and offers the best of both worlds.
A typed value along with a way to test if it exists.
For certain types of pins and functions this very useful as some boards don't have certain pins and it can be useful in some cases.
For example, it can be possible to detect if a board has certain pins and potentially crash the compile with a reasonable message.
Or in some cases alter the code to deal with it not being present like the case of not having a built in LED.
 Or to determine if a particular analog pin exists or if SPI h/w pins exist etc...
There are some nice things that can be done in libraries by having the additional information.

--- bill