= Intro

The Flex NodeMCU and the Flex Red Devil are tools specified to interact with ESP8266-based modules. They're shipped worldwide and many appreciate the simple and robust design. These programmers should not create problem(s). However, on occassion, it might happen you don't get it running the first time. It's likely the reason why you're reading this. Well, here's the long awaited troubleshooter for you.

The NodeMCU programmer is a really rock-solid design. I designed these programmers. I know the ins and outs at hardware-level. Besides, I've tried to design these programmers to get them rock-solid and (almost) foolproof.
Each programmer got assembled by hand and soldered, either by a hotplate, hot-air and solder iron. Next, it undergoes verification-tests, right before packing.
A non-functional programmer can be related to hardware and/or software issues.

Sorry, my mistake
A programmer can arrive at your location as DOA (Dead On Arrival). Like mentioned before, they're assembled by hand, tested and at the end, shipped out to you in a protective package. Something might went wrong during this process.

  • Assembly
    I'll be open and honest with you : I sometimes make mistakes too when assembling these programmers. Those are rare occasions and I've to admit, it can happen. In such case, they're related to soldering-issues, like :
    • Misalignment
    • Cold solderjoints
    • Fractional shorts

    Best practice is to check following components :
    • USB-to-UART bridge (bottomside : MLF package)
    • Power-regulator (bottomside : SOT package)
    • Duo-transistor (bottomside : SOT package)
    • Clamp pins (topside)
    • Pins USB-socket (topside)

  • Shipping
    Damage may occur while being in transport to your address. Once I received an angry mail, including a picture of a completely smashed programmer at arrival. Trust me, I don't ship them them out in such condition. It's annoying to notice this, while each order got carefully shipped in a protective package (airbubble envelope or carton box).
    At some countries / nations, mechanical processes are causing damages, sometimes even heavily frustrated postal office employees. The smashed programmer, for example, was caused by someone (postal employee) who willingly tried to crush a package by stepping on it. It's frustrating for the receiver if this happens. I don't "appreciate" such service or treatment either. There's nothing to do about, shit just happens.
    Typical damage which will occur while in transport to you, is a broken LED, dented USB-socket, bent 8-pin socket or broken / loose clamp pins.

So, if above issues are ruled out, the problem must be located elsewhere.

Who else can be blamed ?
Recently I noticed it's a kind of sport to find a scapegoat, preferably someone else than ourselves. A "DOA" at this level can still be hardware-related and / or software-related.

  • Software
    There are several Operating Systems (Windows, Mac OS and Linux-based). Same goes for the languages you can program and programmingtools to write sourcecode. In other words : there are many combinations available. Don't expect me to be an expert on each and all of them.
    You can find many internet-forums, which cover your specific OS, programming language and softweare programming tools. Best is to pay them a visit and drop your questions. Try to find info, especially if you're new / novice. Several experts are willing to help you, concerning hints, tricks and "do's and don'ts".
  • Hardware
    Hardware-issues are related to "stuff" which is not in "perfect condition". Using an worn out USB-cable, defective USB-port at a computer, using an AC adapter or DC adapter beyond specs, etc.
This troubleshooter is ment to figure out what could be causing a non functional NodeMCU programmer. Over time, I got contacted by users for help to pinpoint a problem. In this troubleshooter I mention all I've seen so far and even theoretical situations which pops-up in my mind, which might cause trouble.

Typos
My native language is Dutch. I do speak English, but not fluently. Please forgive me if I made grammar mistakes or typos. After all, it's about the content of the message. So, let us go down the rabbit hole.


= Step by Step

Below are several topics and tests, which share important knowledge, experiences and some interesting background-info. I know, several steps, you might think : "Oh, I can skip that !"
Please note the following saying : "Assumption is the mother of errors".
This troubleshooter took serious time to write. Please take your time to read it.

Topics are :
Step 1 : ► Basic Setup

To create a reliable condition, please make sure :

  1. Driver for SiLabs CP2102 is installed
    A driver is a kind of digital instruction for your computer OS. It holds a protocol about how to communicate at hardware-level. This means, the computer is informed about how to talk, at what speed and in what language. If this is missing, a computer might detect there's something connected, but doesn't know how to "talk" to this device.
  2. No ESP-module inserted in programmer
    By default, a USB-port will source 5V DC at a current of 100 mA. Onboard are some electronic components, which require energy (read : current). Think about the onboard UART-converter (CP2102), LEDs and power-regulator. An ESP-module is most of the time consuming a current well over 100 mA. This means there's no margin to also hook up an ESP-module.
  3. Powerswitch is set to USB
    To skip the chance a malfunctioning external (switching) power-adapter is causing a potential problem, the programmer should get its power over USB.
    USB-voltage is defined as a "5V DC". Because it's difficult to generate exactly 5.00 V DC, an actual Voltage-range between 4.75 and 5.25 Volts DC is marked as acceptable. The programmer is designed to operate in this range.
  4. USB-cable is connected to computer / laptop and programmer
    The programmer requires energy, but also a way to communicate. This is done by a physical cable : the USB-cable


Step 2 : ► LEDs
Onboard are 2 important LEDs. Both are located near the USB-socket at the programmer. The picture below, shows them marked as 1 and 2.

The one indicated as 1 is a blue one. The purpose is to verify an USB-connection is made. (It's NOT a confirmation for data-transmission).
The other LED (2) indicates 3.3 Volts is present. This is probably a red LED. Some programmers, use a green one. To keep it easy in this troubleshouter, I'll still call them red.
If both LEDs are on, the programmer passed the first test. If not, one of following occurs :

  • No LEDs on
  • Blue LED on, Red LED off
  • Blue LED off, Red LED on
To locate the problem, check the following :
  • USB-cable quality
    USB-cables are sold in many qualities. Some sellers sell low-budget USB-cables. The price feels right, but the quality might be questionable. Inside an USB-cable are 4 small color-coded cables for power and data-transport. To get a flexible USB-cable, each color-coded cable is made of stranded wires enclosed in a flexible, protective, plastic layer.
    Those stranded wires should be made of copper to enable good conductivity. To cut costs, manufacturers look for alternative paths. The choice they make, might have serious negative effects, concerning conductivity.
    Some use a cheaper metal (i.e. aluminum), alloys or even zinc-coated copper strands. Another trick is to reduce the amount of copper strands and / or use thinner copper strands. This is not always clearly visible when using a thicker, protective plastic layer. An easy test : connect different USB-devices to your PC, while using this cable.
  • USB-cable length
    The longer a USB-cable will be, the less conductive it is. The Voltage might drop below 4.75 Volts or data-signals are distorted. If I'm correct, a USB 2.0 cable should be shorter than 5 meters (approx. 16 feet). Shorter is better : 1 meter (3 feet) should be perfect. Don't excagerate by using a too short cable. This will be less comfortable to use.
  • USB-connectors at cable
    If a cable is frequently plugged in and out, the end-connectors might have been bent multiple times. The downside of flexible cables, are stretching and torsion forces in relation to these stranded wires. They tend to break after a while. Also, when a connector is inserted with a excessive force, the metal casing might got dented or even internal connection-pins might be damaged.
    It's just a fact of physics. A new and fresh USB-cable might overcome this problem.
  • USB-port at computer / laptop
    On occasion a computer USB-port is not working as should be expected, like :
    1. Not internally connected (computers)
    2. Powersource malfunction (laptops and computers)
    3. Shortcut-damage at USB-port (computer / laptop)
    4. Dented port (computer / laptop)
    5. Bend or curved pins (computer / laptop)
    To rule these out, try a different USB-port, a different computer, or use an external USB-adapter.
  • No red LED
    If the blue LED is on, but the red LED not, the problem is likely located near the powerregulator. This regulator is located at the bottom of the programmer. The powerregulator is a tiny 5-pin black device, near a tiny black rectangular component and 2 brown rectangular components. Please verify there's no short between two or more pins.


Step 3 : ► More LEDs
This step is verifying if onboard clamp pins and Status-LEDs are working as they should. These LEDs (3) are white LEDs.

These LEDs indicate if a socket-pin is set high or low. Make your index-finger wet and slide across section (4). Whenever you touch a single clamp pin, a LED should turn on (dimmed), located 3.


Step 4 : ► Driver settings

Communications between computer and the programmer, parameters / settings are set to certain values.
There are several Operating Systems, from Windows to Mac OS and several Linux oriented flavours. It's important your OS is aware how it should communicate to the programmer. For this a driver is required, in order to generate a virtual COM-port.
Next, it's important to set the correct communications-protocol. For these you need the following values : 115200, 8, N, 1.

  • Baudrate : 115200
    The baudrate is the rate at which information is transferred in a communication channel. In the serial port context, "115200 baud" means that the serial port is capable of transferring a maximum of 115200 bits per second.
  • Data Bits : 8
    A serial port transmits data bit by bit over a single line. The sequences of bits are grouped into data series beginning with a start bit and ending with a stop bit.
  • Parity : N(one)
    Parity is a method of detecting errors in transmission. When parity is used with a serial port, an extra data bit is sent with each data character, arranged so that the number of 1 bits in each character, including the parity bit, is always odd or always even. ... None (N) means that no parity bit is sent at all.
  • Stop Bits : 1
    The stop bit is used to signal the end of a frame. The data is contained in the data bits and the parity bit is an extra bit that is often used to detect transmission errors.


Step 5 : ► Strings loop

A string loop-test is to verify if data can be sent to and received by a serial UART-line (read : COM-port). For this you need to connect pins Tx and Rx (5). By this, a loop is generated. Data received over Rx will be "bounced" back over Tx-pin.

Open a serial-port tool i.e. CoolTerm and make a connection to the programmer, by selecting it's serial COM-port. Send some strings of text (characters or numbers) to the programmer. There are 3 scenarios as a result :

  1. All OK
    You get exactly the same strings returned.
  2. Response, but not identical
    You may see odd looking characters returned. Most of the time, this is related to incorrect communication-settings. Often it's all about the Baudrate, which was not set to 115200 kBps.
    Verify if the driver-settings are identical to the settings for serial-port tool
  3. No response
    There's a fair chance this is hardware-related. It could be a bad connection for one or more pins, like a cold solderjoint. Also a missing pin-connection at CP2102 is possible.
    You might consider using a multimeter to verify if all clamp-pins are connected to the female 8-pin socket.
    However, in general it means the programmer requires a repair or should be replaced.


Step 6 : ► Limits to USB-Power

Powerconsumption for an ESP-8266-module varies a lot. It can run one moment at 50 mA, next moment it requires a solid 550 mA.
There are several versions USB-ports : 1.0, 2.0, 3.0 and higher. In theory a total of 127 devices can be connected to a single USB-port. Some devices are powered by USB-port, others use batteries or external power-adapter.
USB 2.0 and lower versions supply a max. of 500 milli-Amps (= mA) total. By default, it supplies 100 mA. If more is needed, a special request / command should be sent from USB-device to USB-port. A problem will rise if more than 5 devices require each 100 mA. Same goes for a single USB-device which requires more than 500 mA. And in case of a shortcut, a whopping amount of current is drawn.
Onboard computers and laptops, current sensing and limiting ICs are used. To trim down costs, low-budget USB-hubs don't have these protection ICs onboard.

So, how to solve a problem about USB power-consumption ?

  • Power-adapter
    This requires some solder-skills. At internet and maybe at your local hardware-store a 6V DC poweradapter can be bought. (Be aware, it should be DC, not AC !) When receiving the NodeMCU programmer, a locking connector, including some metal pins are included. These can replace the original connector at the power-adapter. Or in case you own a regulating bench powersupply : create a small cable, which will fit the programmer.
  • USB-hub
    It's clear what to look for. A "dumb" USB-hub, including a power-adapter (600 mA or more). Most of the time, these hubs are 1-port IN (computer to hub) and 4-ports OUT (4 USB-devices).
  • Modify powersettings CP2102
    This is do-able, but not easy. Software for the CP2102 can be downloaded from SiLabs. This can "program" the CP2102 to request the full 500 mA. Once done, un-install this software, otherwise you can't connect to the NodeMCU programmer as a COM-port.
    Important note : Some laptops are designed to be less energy-consuming and consequently, so are their powersupplies (internal or external).
  • USB 3.x or higher ?
    Newer versions of USB do support higher currents. It might work, or not. Do they also source a default minimum like 100 mA or is the limit set higher ? The NodeMCU programmer requires a max. of 550mA and I'm sure this USB-version can supply this amount. Only,. I'm not aware about the "howto". It'll probably not generate a problem at all and in some cases it might. It's a guess and requires a trial and error approach.


Step 7 : ► Inserting ESP-module

This is the part, I can't be held responsible for. This is mostly based on knowledge you gained as a user or other people who wrote software or guides.

  • Flash / Reset
    Flashing and resetting is required in a certain sequence for an ESP-module. This is often an overlooked topic. If you're new to these modules, please let me emphasize this : do get basic knowledge about the langauge you like to start coding. Onboard are functions for "flashing" and "resetting". These are the 2 onboard buttons, but also can be set by software. But don't assume the programming tool does this automatically for you. Verify if it is supported.
  • New to ESP-modules
    If you're new to ESP-modules, don't assume it'll work right away. Some people overlooked the fiddling between flash and reset-buttons. Source-code errors do happen also (on a frequent basis). It requires experience to become a good coder. At internet are several fora, dedicated to certain programming languages. I'm sure there's one which will fit you. People are willing to help and support you overthere.
  • Bugs
    You might stumble into an anomaly, when writing sourcecode or try to program an ESP-module. Especially if you like to newest tools or even Beta-versions. If you're new to the ESP-8266, stay at the safe side and use proven tools and versions.


= The end

Well, thats about it. I've tried to cover all type of possible causes I can think of, or ran into. I will never claim : "The NodeMCU programmer can't be the problem."
But I may say that majority of the claims for a defective NodeMCU-programmer, were related to novice users. Below is a list of actual reasons, causing false claims for a DOA.

In complete semi-random order :

  • USB-power-problem
  • defective USB-cable
  • CP2102-drivers
  • correct driver-settings
  • RESET or FLASH-button usage
  • didn't know why or how to flash an ESP-8266 for the programming environment / language
  • ESP-8266 module DOA
  • weak solder-joint at the ESP-8266 module
  • incorrect flashed onboard EEPROM (ESP-8266)
  • fake or wrong version ESP-8266 module
  • needed a programmer for just a day ☹

The NodeMCU programmer is a proven and robust tool. Updates are only ment to increase reliability or to improve "foolproof-factor". Examples for this claim are :

Polarity Voltage protection
Clamping socket-pins
Drillholes for mounting
LEDs as status-indicators
Reliable and well supported USB-UART converter

Maybe this troubleshooter didn't help you. And indeed, I wouldn't be suprised if something completely new popped-up. Shit happens.