Last edited · 30 revisions  


The Wifi-Bluetooth Add-on

This OnStep add-on provides a Wifi adapter which can be used to connect to OnStep wirelessly from a cell-phone, tablet, or laptop/desktop computer.  It has both a web-server and IP command channel (on port 9999.)  Programs such as Sky Safari, my ASCOM driver, and the Android App can use the IP channel.  There is also support for A/B quadrature and pulse/dir encoders in this firmware.

The hardware consists of basically any ESP8266 device but we recommend either an ESP-01 or the WeMos D1 Mini

The ESP-01 is appropriate for the MiniPCB design since it's compact and allows flashing new firmware into it through the Teensy3.2 (running OnStep.)  There is some external circuitry required for this which is provided on the MiniPCB.  Encoders are not supported on the ESP-01 since it doesn't bring out enough pins to attach them.

The WeMos D1 Mini has the advantage of an onboard 3.3V voltage regulator which allows it to run from a 5V supply.  This is important for Mega2560 based builds (and others) since its onboard 3.3V regulator isn't able to power an ESP-01 (3.3V only) but its 5V regulator can power a WeMos D1 Mini.  Flashing the WeMos D1 Mini is also easier since it's "stand-alone" and can be plugged in via USB and flashed similar to any other Arduino IDE compatible board.


If you are using a pre-wired board (e.g. MiniPCB, MaxPCB), you don't need to worry about wiring, since it is all done for you.

If you are not using a pre-wired board, you have to connect your ESP8266 to certain pins for your microcontroller. Basically, the TX on the ESP8266 should be connected to an otherwise unused serial port RX on the microcontroller, and RX on the ESP8266 should be connected to and otherwise unused serial port TX on the microcontroller.

Serial channels in OnStep are designated with a letter A, B, C.

  • A is always the Serial/USB channel (where programming normally happens) and is always occupied (not available.)
  • B is the first available Serial port.  Normally Serial1 (Mega2560, Teensy3.x) but the STM32 uses Serial3 (PA10/TX and PA11/RX.)
  • C is the next available Serial port.  This is Serial2 (for a Mega2560) or Serial4 (for a Teensy3.5/3.6) and isn't available on the Teensy3.2 or STM32.

Note: SERIAL_B or SERIAL_C can be used for Bluetooth, Wifi, or Etherent, or RS232, etc.

Note: You also need to make the CHPD/EN pin high by connecting it to 3.3V, otherwise, your ESP-01 would not turn on.

Note: Serial2 on a Mega2560 is only available if using the latest Alpha branch OnStep.

Attention: In no case (WeMos D1 Mini, Node MCU, Mega2560, STM32, etc.) should you use the TX/RX pins that are attached to the microcontroller's serial to USB chip!  Those consist of two serial devices talking to each other and adding another will damage hardware.  For a WeMos D1 Mini, for example, the swapped port location should be used (set in Config.h) to change the Serial default location GPIO 1(TXD0)/3(RXD0) to 15(TXD2)/13(RXD2.)  For a WeMos D1 Mini these pins are labeled D8(TXD2) and D7(RXD2.)


These modules require more power than the 3.3v regulator on a Mega2560 can supply so the WeMos or NodeMCU with on-board regulator can be handy.  The Teensy3.2, Teensy3.5, and Teensy3.6 have 3.3v regulators capable of running an ESP-01.  The 3.3V regulator on an STM32 "BluePill" is NOT capable of running an ESP-01.

Installing the ESP8266 Platform

Before you can flash the firmware on your ESP8266 device, you need to install the ESP8266 platform for the Arduino IDE.

Under Preferences add this line in the additional "Boards Manager" area:

Then from the "Tools, Boards, Boards Manager" menu select and install the latest ESP8266 add-on.

Getting OnStep ready for using the WiFi Server

No special configuration of OnStep is necessary EXCEPT for cases where you wish to flash an ESP-01 (or similar) through the OnStep MCU (for example, a MiniPCB build w/Teensy3.2 where you have devoted the Aux1 and Aux2 pin options to ESP-01 GPIO0 and RST control.)  In this case you need the #define ESP8266_CONTROL_ON option in OnStep's file.  Then, just before flashing the ESP8266 firmware set the serial port address to OnStep's port and open the Serial Monitor.  At 115200 baud send :ESPFLASH# and you should get a message telling you that it's ready and "Waiting for data."  You can then upload to the ESP-01.  It is required that OnStep be idle for the :ESPFLASH# command to be recognized.  For most users just turning OnStep on places in the correct state but for those with #define AUTOSTART_TRACKING_ON you can send :hF#:ESPFLASH# instead.  Once done CLOSE THE SERIAL MONITOR before unplugging/powering off since it'll keep windows from assigning the port again when you power back on/plug in.

Flashing The WiFi Server

The exact flashing procedure depends on which ESP8266 device you will be using.

In the Arduino IDE, pick your device from "Tools, Boards".

For a WeMos D1 Mini or NodeMCU, select the device from the list.  Since these devices have a USB port you can connect directly using the USB connector.

  • For a WeMos D1 Mini I've always used the Arduino IDE default (but upload at 115200 baud.)

For an ESP-01, select "Generic ESP8266 Module".

  • For flashing an ESP-01 module, its pins should be in a certain configuration. 
    • Pin CHPD/EN must be HIGH (connected to 3.3V) Pin GPIO0 must be LOW (connected to GND). 
    • You can buy an inexpensive adapter or board that help with flashing the ESP01 from eBay, Amazon and other sources.
  • For the ESP-01, the following parameters under Tools has worked well:
    • Board: "Generic ESP8266 Module"
    • Flash Mode: "DIO"
    • Erase Flash: "Sketch + WiFi Settings"
    • Flash Size: "1M (64K SPIFFS)" (Most ESP01 have 1M, older ones have 512K)
    • Flash Frequency: "40MHz"
    • CPU Frequency: "80 MHz"
    • Reset Method: "ck"
    • Upload Speed: "115200"
    • Debug Port: "Disabled"
    • Debug Level: "None"

The source code is inside the OnStep folder under the "addons/WiFi-Bluetooth" subdirectory.  Open the WiFi-Bluetooth.ino file inside this folder. Check the "Config.h" file for information about serial port wiring and to configure before uploading.

Once this is done upload to the ESP8266.

Once uploaded, power off OnStep and the ESP8266, wait a few seconds, then restore power.

Start Up Sequence

OnStep and the ESP8266 both use a default serial port baud rate of 9600.  On startup the ESP8266 sends a command to OnStep to change this baud rate up to a higher operating baud (you should have configured 19200 for a Mega2560 or 57600 for Teensy3.x, STM32, etc.)

The WiFi web server and command channel will only start if the ESP8266 is able to connect to OnStep and get a valid reply for this baud rate change. Otherwise, you will not be able to connect to the website or command channel though you might see the "ONSTEP" (from successful reaching this stage before) or other default SSID since the WiFi section in the ESP8266 remembers its settings but that doesn't mean my firmware has started up the servers.  During this time you might notice repetitive flashing of the ESP8266's serial LED at four second intervals as my firmware (evidently unsuccessfully) tries to get a valid reply to the baud rate change up command.

You can replace DEBUG_OFF in Config.h with DEBUG_ON to change this behavior, and allow for resetting the configuration on the ESP.  You can also change the default and operating baud of both OnStep and the ESP8266 to be one and the same (19200 or 57600.)  This disables the baud rate change up and lets the web and command channel servers come up (without confirming OnStep's presence.)

Once It's Working

When you power on your OnStep controller you can connect to the Wifi add-on access point from a computer of cell-phone.

  • Connect to the Wifi SSID OnStep.
  • Open a browser, and enter to reach the website.
  • Or open Sky Safari, the Android App, ASCOM driver and use for an IP connection.
  • To change the SSID or IP address to something else or to switch from Access Point mode to Station Mode select the WiFi tab and re-configure.

Flashing Trouble

Many users report problems getting the modules to flash and operate.  Typically when this happens I do NOT see an SSID which leads me to believe the ESP8266 never starts up at all.  To resolve this I repeatedly flash the ESP8266 with the same exact firmware (no settings changes) until it starts up.  This has happened to me on WeMos D1 Mini once or twice (two separate sources from eBay) but for ESP-01's (three separate sources from eBay) it happens frequently usually requiring 2 or 3 flashes before a module starts working (one took five times.)  The root of this trouble is unknown to me but it seems unlikely to me that it's related my firmware/source.

Another cause of trouble is the flash chips on a given module not working with the selected Arduino IDE mode (QIO, DIO, QOUT, DOUT.)  I would provide guidance here if I could, but that seems to be impossible to do, so you'll have to experiment.

And finally, you can configure the settings of an ESP8266 (on the Wifi web-page and saved in EEPROM) so it can't be accessed which is dealt with in the next section...

What to do when you get Locked Out!

If locked out of the ESP8266 (due to an unsuccessful attempt to operate in Station Mode for example,) there are a couple of ways to reset the device settings to default for normal operation. 

One method involves sending an 'R' in reply to any '#' received while the ESP8266 is trying to communicate with OnStep on its serial interface (normally at 9600 baud.)  This will cause a reset to AP only enabled and the default SSID/Password. 

  • For an ESP-01 this interface is only attached to the device running OnStep (Teensy3.x, Mega2560, etc.) so a Sketch (like MultiSerial) uploaded to the MCU instead of OnStep can then pass those communications through the the Arduino IDE serial monitor where you can send the 'R'.  Be sure to upload OnStep again and then restart both devices to resume operation.
  • For a WeMos D1 Mini or Node MCU you can instead configure the serial channel to the default (not swapped) location by plugging the device in via its USB interface (disconnect it from OnStep first!) and uploading the wifi-bluetooth add-on firmware again.  Open the Arduino Serial Monitor and send the 'R' across the USB interface to reset the device.  You'll then have to set #define SERIAL_SWAP_ON and upload again to use the device with OnStep.

Another method, that some users report success with, is to use the Arduino IDE ESP8266 option to clear flash (and so reset defaults.)  I have no personal experience with this technique, so use it at your own risk.  This is done by switching the menu option Tools->Erase Flash "Only Sketch" to Tools->Erase Flash "All Flash Contents".

Other methods are detailed in this email on the messaging list.