NodeMCU PIN reference

  • Hello!

    I am struggling with how I should refer to the different GPIOs vs PINs in my code. I have been looking at the library source code and different example code, as well as the complete pin mappings of the NodeMCU, and i find disparities.

    For example in the code for the ESP8266 WiFi Gateway ( all comments about which GPIO to connect the radio correlates correct to the PIN layout.
    Then it says to connect the inclusion button to GPIO5 which is PIN D1. Later in the code it defines inclusion button to PIN 3, which is GPIO0.
    To confuse it even more, the same example code later uses PIN 16 which is the internal LED on the board...

    And the next confusing thing is how I refer to the analog PIN on the board? On the board there is only one analoug PIN, named A0. How do I put that one in the code for soft signing? I have seen example of both "0" and "A0". Which is the correct?

    Is there any where I could find a complete reference for the PIN vs GPIO for the ESP8266 in the MySensors library?

  • Mod

    @Strixx the MySensors library does not have a pin reference.
    The pins are defined by the board definitions.
    See here for the NodeMCU Dn pins and BUILTIN_LED
    See here for the A0 pin.

    These definitions are just aliases. So A0 is an alias for PIN_A0 which is an alias for 17. You can use any alias you like, they will all result in the same code. I like the PIN_A0 notation because I think it is very clear that you mean the pin called A0 and that makes the code easier to read. But you can write 17 in your code and the code will work the same way as with PIN_A0.

    For details on how the esp8266 works, I recommend Kolban's book.

  • @mfalkvidd Thank you!

    Then I had it all figured out any way and the code for the ESP8266 WiFi Gateway ( is not correct when it comes to the inclusion button. Either the comments on which GPIO the button should be connected to or the PIN assignment should be changed.

    Once more: Thank you for your help!

  • Mod

  • Mod

    @Strixx dit you get the inclusion button working? If so, what pin did you use?

  • @mfalkvidd I have not started building it yet. Hopefully I will have some spare time tomorrow, otherwise it will be in a week or two. I will get back as soon as I have got it all up and running (with external radio traffic LED as well).

  • Mod

    @Strixx great, thanks! It seems like GPIO5/D1 is better suitable than GPIO3/D9 because GPIO3/D9 is connected to serial RX so connecting a button might interfere with flashing.

  • Mod

  • Back to testing the inclusion button, now that the gateway is up and running.

    I am trying to see in serial monitor, MYS Controller and Domoticz to see if it works, but nothing.
    What would be the easiest way to see if the function actually is working?

  • Mod

    @strixx to my knowledge, Domoticz does not support inclusion mode. I have never used inclusion mode so I can't help much unfortunately.

  • I believed that adding this button to the gateway would set Domoticz to accept new hardware, when the button was pushed. But now that I have investigated some more it seems that this button is only used in Vera? Maybe there is a way to add this function in Domoticz, but that's for later.

    Anyway; since I started this "issue" I want to finish it, even if I have no use of the button.

    Is there any way to see if the gateway sends anything to the controller when I push the button?
    I cant see anything on the serial output.

  • Mod

    @strixx I didn't know, so I checked with the team and this is the info I got:

    The gateway should send a start inclusion internal command when the button is pressed… and after X seconds in should send a inclusion end command.

    So testing it should be fairly straightforward.

  • Mod

  • Mod

    Verified now (thanks to @hek) and merged. The fix is available in the development branch and will be included in the next release.

  • @mfalkvidd That is perfect.
    I have been buisy with another projects. But I did quite a lot of trials, and could not get it to work for me no mater what i tried.
    But now I see what was the problem. I was assigning the pin with only a digit. IE 1, 3, 4. But with D1, D3 and D4 it works. I was under the impression that 1 = D1, but it's not.

    Now that I got it working I have noticed a strange thing. When using MYSController for debugging I can only sometimes se the inclusion message sometimes in the "log". But always when logging with netcat. I have not been able to see any pattern for when MYSController is not showing the message.

    May I suggest another PIN for the inclusion button?

    As I understand it. With the NodeMCU 0.9 that I'm using there is only a limited number of pins left to use after connecting the radio. D0, D1, D3, D4, D9 and D10. And some of them have special purpose. And if you want to use external leds for rx/tx/err (instead of the internal led as used by the example) there are (as I understand it) only three pins left, and that is D1, D9 and D10. But D3 and D4 should be safe to use for inclusion button, since they only have special use at boot. So as long as you don't press the inclution button at startup of the gateway they are safe to use as input.

    My suggestion, which I have been trying with out problems the last couple of hours, is that:

    #define MY_DEFAULT_ERR_LED_PIN D10  // Error led pin (Red)
    #define MY_DEFAULT_RX_LED_PIN  D9  // Receive led pin (Yellow)
    #define MY_DEFAULT_TX_LED_PIN  D1  // Transmit led pin (Green)

  • Mod

    @Strixx I guess you didn't see this reference earlier?

    See here for the NodeMCU Dn pins and BUILTIN_LED

    It shows that numbers the Dn aliases are mapped to. 🙂

    As for changing the example to D4: if you are sure it doesn't interfere with boot go ahead and create a pull request.

  • @mfalkvidd said in NodeMCU PIN reference:

    See here for the NodeMCU Dn pins and BUILTIN_LED

    I shows that numbers the Dn aliases are mapped to.

    Yes I did. I don't know why I have been trying with only digits without the D in front. I have been reading up on this project a lot, and I think I have seen somewhere that both Dx and x have mappings to GPIO. But maybe I have been reading in some old source or maybe that is only for Arduino. Or maybe I am only dreaming. But I do feel a bit stupid now... 😕
    (But in my defense, in the example code for the gateway the LED pins are only referenced by a single digit)

    As for the pull request. I consider myself to much of a newbee to be doing that. Even suggesting to the professional here in the forum is a bit scary.. 🙂

  • Mod

    @strixx I feel stupid quite a lot. Learning (and especially re-learning) can be painful 🙂 But rewarding in the end.

    Pull requests aren't for everyone. It is a great way to get things done though. Without a pull request, things just end up on someone's todo list, and for most open source projects those todo lists are pretty long.

    Would you mind creating an issue?
    Just describe the change, why you think the change is good and why you think it won't break anything. With an issue created, your suggestion will at least be added to the todo list. Here in the forum it might get lost.

  • Ok. Will do some more testing to be sure it works as expected, and then create an issue.

  • Mod

    @strixx Kolan's book on esp8266, says the following on using D4

    Used for UART1 output and, as such, is likely to be used
    during development time for debugging. Written to when
    flashed with new firmware.

    I think most MySensors users use the usb port for debugging so using D4 for inclusion pin should be safe, as long as nothing tries to print to UART1. I don't know if anything uses UART1.

  • @strixx
    👉 BEFORE YOU USE analogRead()
    You need to be aware that the MySensors core Ver 2.2 has code to support sensors reporting the chip VCC voltage. As I recall, this code is enabled by default and all readings of the analog port will return 65,535, -1 or hex FFFF, depending on the type of variable you read the value into regardless of what voltage is applied to the analog pin. MySensors has changed the 8266 configuration to read the chip VCC and ignore the analog input and I gather the MySensors coders decided to return 65,535 as an indicator.

    You will need to do a search for "ESP analog read" or similar, to find the correct syntax of the special command to change the 8266 mode to re-enable reading of the analog input pin. Note: this analog mode command must be placed at the top of your script before any other functions.

    Please be aware the analog pin 'hardware' varies with different NodeMCU devices and you need to understand how the MySensors restricts how you can use this pin.

    First, I have encountered three different 'NodeMcu Ver 1' boards. Traditionally the analog pin expects a range 0V to 1V max. Some docs state going over 1V can destroy the pin, others state it can tolerate 0V to 3.3V but the anagloRead() for voltages of 0V to 1V are as expected, but 1V to 3.3v returns the same value.

    On the earlier boards I received, the analog pin of the PCB was wired direct to the 8266 chip (in the metal can) and not connected to anything else.

    About a year ago, the boards I received had additional circuitry to protect the analog pin from excess voltage.

    More recently I have received a batch of 20 boards which returned values lower than expected? Suspecting a board problem, I traced the circuit and confirmed there is a voltage divider which scales an input of 0V to 3.3V to become 0V to 1V at the actual 8266 chip. I.e. these boards requiire a 0V to 3.3V input on the analog pin. If you code reads values about one third of what you expeted, you may have a 0V to 3.3V board.

    As a final tip, I have noticed that no two NodeMCU's return the same value from the analog port. I.e. five 'identical' boards from the same batch will return slightly different values, unlike the Arduino devices, which I find all return accurate readings.

    My assumption is, this is due to the 8266 using a different analog to digital conversion method, and the errors are 'possibly' due to some capacitive effect. The differences or minimal, can can be confusing and may need special attention if you are checking for a 'specific' value. Hint: always code analogRead comparisons to look for different 'ranges' of values, rather than "if analogRead(A0) == 350", because the value you get today could be different tomorrow or next week. This is good practice because the value read will vary slightly as your project's supply voltage changes due to changes in load (e.g. several LEDs turned on vs off), or even if your battery or even mains voltage is unstable.

    Hope this saves someone banging their head against a brick wall for hours like I did.🤕