NodeMCU-compatible pin numbering

All ESP8266 boards running MicroPython.
Official boards are the Adafruit Huzzah and Feather boards.
Target audience: MicroPython users with an ESP8266 board.
Post Reply
User avatar
Posts: 1374
Joined: Thu May 28, 2015 5:54 pm

NodeMCU-compatible pin numbering

Post by deshipu » Wed May 04, 2016 5:23 pm

Due to popularity of the NodeMCU firmware, many ESP8266 boards have the wrong gpio pin numbering on them -- compatible with how NodeMCU for some reason remaps them. I wonder if it would be helpful to have a simple compatibility layer for users of such boards, so that they can use the numbers that they see on their boards.

Right now I'm thinking about including something like in the scripts, with something like this:

Code: Select all

import machine

class Pin(machine.Pin):
    def __init__(self, index, *args, **kwargs):
        super(Pin, self).__init__((16, 5, 4, 0, 2, 14, 12, 13, 15, 3, 1, 9, 10)[index], *args, **kwargs)
And then the users could replace their "from machine import Pin" with "from nodemcu import Pin". What do you think?

User avatar
Posts: 3455
Joined: Mon Jan 06, 2014 6:08 pm
Location: Peachland, BC, Canada

Re: NodeMCU-compatible pin numbering

Post by dhylands » Wed May 04, 2016 8:47 pm

The Pin interface on stmhal (not sure about the ESP8266 one) allows for a user-supplied mapping dictionary to be provided and/or a transformation function.

Posts: 1155
Joined: Fri Feb 28, 2014 2:05 pm

Re: NodeMCU-compatible pin numbering

Post by pfalcon » Thu May 05, 2016 2:39 pm

Right now I'm thinking about including something like in the scripts, with something like this:
I think paradigmatically it's wrong. MicroPython port went a long way to work on as many esp8266 boards as possible, and you strike that out and want to favor one board to disadvantage of all the rest. If such "" will be included in public projects, there will be just unneeded fragmentation in the community, with some scripts using standard pin mapping and some - adhoc (various adhoc).

Of course, nobody can preclude your using such a mapper with your own projects. (Nobody can preclude you from making it public either, but from the above, that won't be "helping community", but "fragmenting community"). All that is of course IMHO.
Awesome MicroPython list
Pycopy - A better MicroPython
MicroPython standard library for all ports and forks -
More up to date docs -

User avatar
Posts: 1374
Joined: Thu May 28, 2015 5:54 pm

Re: NodeMCU-compatible pin numbering

Post by deshipu » Thu May 05, 2016 3:22 pm

I'm not sure how this is fragmenting the community, as the scripts would use the default pin numbering internally, and thus would work perfectly fine on all ESP8266 boards. The only thing this provides is a convenience in translating the pin numbers between the GPIO and the nodemcu notation.

In fact, this has a potential of actually healing a schism in the ESP8266 community caused by NodeMCU arbitrarily renumbering the pins on their boards. It would make it easier for the LUA users to switch to Micropython.

Note that Arduino has a similar thing, where the pin numbers used with digitalWrite are completely different from the PORTX/bit numbering from the datasheet. I don't see a horrible divide in the community because of that. I'm very happy that Micropython is board-agnostic and choose to use the GPIO numbers *by default*, but I'm not sure if having an easy way to convert to the second de facto standard is such a horrible thing.

Perhaps a different way of doing the translation would be less disastrous to the community? For instance a "from_nodemcu_pin()" function or method on the Pin class? I'm not pushing for this, but I think it would be nice to at least discuss the possibilities. Perhaps not necessarily right now, as there are more important things to do, but eventually?

Posts: 34
Joined: Thu Mar 10, 2016 7:43 am

Re: NodeMCU-compatible pin numbering

Post by Llwy » Fri May 06, 2016 7:08 am


For what it's worth, I agree with Dave's comment and I would personally find it very useful to have a user supplied dictionary or list.
This could be something like machine.SetConvenienceMapping(mydictionary)

Not a vital feature but indeed something very convenient.


Posts: 1
Joined: Thu Aug 24, 2017 8:52 pm

Re: NodeMCU-compatible pin numbering

Post by anselm » Thu Aug 24, 2017 9:02 pm

Hi Guys,

I have a NODEMCU V2. I had the same issue, so I go through each Pins, set it to ON, then OFF and manually checked through all data pin-s for results...

The outcome is the following:

Micropython | Board
2|D4 (also Led1 but inverse)*
16|D0 (also Led2 but inverse)*

The two highlighed pins are also connected to the on-board leds. When setting the, it will turn on the onnoard led and vica versa.
Correct me if I'm wrong, for smaller things (DHT22 and such) it's a good start.

User avatar
Posts: 4471
Joined: Fri Jul 18, 2014 8:01 am
Location: UK

Re: NodeMCU-compatible pin numbering

Post by pythoncoder » Sun Aug 27, 2017 9:09 am

As far as I know the machine module doesn't support a mapping dictionary, but I've never felt the need for one.

I'd pass ESP8266 pin names to the constructor and have the hardware mappings in the docs. After all, you only need to consider physical pin numbers when designing a PCB, wiring it up or attaching testgear; then a mapping table or schematic is your friend. If you use functional names for your pins (e.g. left_motor) the code is self documenting. IOW keep the logical to physical mapping for each target in the docs rather than in the code.
Peter Hinch

Post Reply