Last edited · 67 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 the WeMos D1 Mini unless you are using a MiniPCB v1.x design where the ESP-01 is required.

  • 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 their onboard 3.3V regulator isn't able to power an ESP-01 (3.3V only) but their 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.
  • The ESP-01 is appropriate for the MiniPCB (v1.x) design since it's compact and allows flashing new firmware into it through the Teensy3.2 (running OnStep.)  There's some additional circuitry required to allow this which is provided on this PCB.

Wiring and Power

If you are using a PCB designed for OnStep (e.g. MiniPCB, MaxPCB, STM32), you don't need to worry about wiring and powering the module since it is all done for you and may skip this section.

If you are NOT using one of these PCB's, you have to connect your ESP8266 to certain pins on your micro-controller.  Basically, the TX on the WeMos D1 Mini should be connected to an otherwise unused serial port RX on the micro-controller, and RX on the ESP8266 should be connected to and otherwise unused serial port TX on the micro-controller.  There should also be ground (Gnd) and power connections (I'd use 5V from the telescope controller to run the WeMos D1 Mini.)

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.


  • Serial channels in OnStep are not specific to a purpose and SERIAL_B or SERIAL_C can be used for Bluetooth, Wifi, Ethernet, or RS232, etc.
  • Use either of the WeMos D1 Mini's default GPIO 1(TXD0)/3(RXD0) or swapped 15(TXD2)/13(RXD2) pins.
  • The Serial1 port on a MKS Gen-L (and possibly other similar boards) has additional circuitry that interferes with the WeMos D1 Mini's operation.  For this reason we recommend wiring to the Serial2 port of this device.
  • The Teensy3.x 3.3V regulator is capable of running an ESP-01 or similar provided it's powered from 5V and no other significant 3.3V loads are present.
  • The 3.3V regulator in the STM32 "BluePill" and Mega2560 is NOT capable of supplying enough current to run an ESP-01 (or similar.) 
  • The Mega2560 (and MKS Gen-L) built in 5V regulator is capable of running an WeMos D1 Mini or similar provided it's powered from 8 to 12V (to 24V for the MKS Gen-L) and no other significant 5V loads are present.
  • Never plug into the add-on's micro-usb while the gnd and power connections to the OnStep telescope controller are connected unless there is a diode installed to block reverse feeding power into the telescope controller.

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. 


  • If you are not using encoders connected to your WiFi module, then you must only use versions 2.6.2, 2.5.2, or 2.4.2. All other versions are known to cause various problems, so avoid them completely.
  • If you are using encoders, you need to stick with version 2.4.2 only.

Configuring the Wifi Add-on

The Wifi Add-on source code is inside the OnStep folder under the "addons/WiFi-Bluetooth" subdirectory and contains its configuration file.

For the MiniPCB version 1.x or other designs using the ESP-01 module:

  • No changes to the Wifi Add-on's default Config.h file are necessary.

For the MiniPCB2, MaxPCB2, or MaxESP2 using the WeMos D1 Mini and its swapped serial port change the following lines in the Config.h file:

  • #define LED_PIN D4
  • #define SERIAL_SWAP_ON

For the STM32 PCB and other designs using the WeMos D1 Mini's and its default serial port change the following line in the Config.h file:

  • #define LED_PIN D4


  • If running OnStep on a Mega2560 also change to "#define SERIAL_BAUD 19200" for this slower OnStep platform.
  • There are other advanced settings in the Config.h file and those should all be left in their default state at this stage.

Configuring OnStep for the Wifi Add-on

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 by positioning the shunts next to the stepper drivers properly.)  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 :hF#: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. 


  • Once done CLOSE THE SERIAL MONITOR before unplugging/powering off so windows can assign the port again when you power back on/plug in.
  • The Teensy's present two ports in the Arduino IDE.  You need to select the virtual serial port called "COMn (Teensy)" for upload NOT the direct USB one called "COMn Serial (Teensy)".

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 similar.

  • Just select the WeMos D1 Mini device from the boards list in the Arduino IDE.  Since these devices have a USB port you can connect directly using the USB connector, just be sure to DISCONNECT the ESP8266 from OnStep before plugging USB directly into it and flashing.
  • For flashing a WeMos D1 Mini through the OnStep MCU's Serial port (MaxESP3 for example,) using the :ESPFLASH# command the following parameters under Tools have worked well:
    • Board: "Generic ESP8266 Module"
    • Flash Mode: "QIO"
    • Erase Flash: "Sketch + WiFi Settings"
    • Flash Size: "4M (1M SPIFFS)"
    • Flash Frequency: "40MHz"
    • CPU Frequency: "80 MHz"
    • Reset Method: "none"
    • Upload Speed: "115200"
    • Debug Port: "Disabled"
    • Debug Level: "None"

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 have 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 tries to get a valid reply to the baud rate change up command (after which it begins operating.)
  • The WeMos D1 Mini has a status LED that will also flash (if configured properly) when trying to connect and will remain solid ON if successfully connected.
  • 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.
  • You can replace DEBUG_OFF in Config.h with DEBUG_ON to change this behavior, and allow for resetting the configuration on the ESP.

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.  The default password is "password".
  • 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 only ever happened to me once or twice with WeMos D1 Mini's, but for ESP-01's it happens frequently and usually requires 2 or 3 flashes (but I've seen it take as many as 5) before a module starts working.  The root of this trouble is unknown but it seems unlikely to be related my firmware or design.

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.

The preferred method is to use the Arduino IDE ESP8266 option to clear the flash memory (and so reset defaults.)  This is done by switching the menu option Tools->Erase Flash "Only Sketch" to Tools->Erase Flash "All Flash Contents" and uploading this add-on's sketch again.

Another 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 can be done using the Arduino Serial Monitor and will cause a reset to AP only enabled and the default SSID/Password.


  • For a WeMos D1 Mini configured to operate on the swapped serial port location you must first configure the serial channel to the default (not swapped) location by plugging the device in via its USB interface (disconnect from OnStep first!) and uploading the wifi-bluetooth add-on firmware again.  You should then be able to send the reset command.  Finally, you'll then have to set #define SERIAL_SWAP_ON and upload to use the device with OnStep again.
  • 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 communications through to the ESP-01.  When done be sure to upload OnStep again and then restart both devices to resume operation.

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