Last edited · 90 revisions  


The WiFi Add-on

This OnStep Addon 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, standard IP command channel (on port 9999) which programs such as Sky Safari, my ASCOM driver, and the Android App can use simultaneously.  It optionally has a persistent IP command channel (on port 9998) where programs such as Stellarium Mobile (for example) can connect one at a time.

There is also support for A/B quadrature and CW/CCW Encoders in this firmware.  From what I read an ESP8266 can handle up to about 10k count A/B encoders.  Limitations in CW/CCW mode are unknown but expected to be in the same range at a minimum.

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

  • 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 due to its small size.

Wiring and Power

If you are using a PCB designed for OnStep (e.g. MiniPCB, MaxPCB, MaxESP, STM32 Bluepill), 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 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 Mega2560 (and MKS Gen-L) 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.
  • The Serial1 port on a MKS Gen-L (and possibly other similar boards) may have 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 3.3V regulator in the STM32 "BluePill" and Mega2560 is NOT capable of supplying enough current to run an ESP-01 (or similar.) 
  • 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 ESP8266 Add-on (see which versions to use below!)


  • 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, it is recommended that you use version 2.4.2 only.

Configuring OnStep for the WiFi Add-on

For the MKS Gen-L where RX2/TX2 is often used for the serial connection the third serial port in OnStep, Serial C, must be enabled in Config.h:


No other special configuration of OnStep is necessary EXCEPT for cases where you wish to flash an ESP8266 through the OnStep MCU:

The MiniPCB version 1 has an option that uses Aux1 and Aux2 pins (via shunts near the stepper drivers) to control flashing the ESP-01.
The MaxESP version 3 has an option that uses just Aux2 (via a shunt near the DS3231 RTC socket) to control flashing the WeMos D1 Mini.

In this case you need the #define SERIAL_B_ESP_FLASHING ON option in OnStep's Config.h file.

Just before flashing the ESP8266 you must then tell OnStep to reset the device into firmware upload mode and pass the serial data on to the ESP8266 serial port.  So, in the Arduino IDE 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 it's ready and "Waiting for data."

You can then have one minute to close the Arduino Serial Monitor and begin uploading to the ESP8266.  If the upload process takes more than a minute to start you must issue the above command again.


  • 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)".

Configuring the Wifi Add-on

Open the Wifi Add-on source code located inside the OnStep folder under the "addons/WiFi-Bluetooth" sub-directory in the Arduino IDE.  In the IDE you will see its configuration file in a tab (Config.h.)  NO changes are required for the WiFi Addon to function properly with OnStep release-3.16 and later.  You can however select a "locale" at this point if you like:  English and German are currently supported in the latest release.  Select a locale using #define DISPLAY_LANGUAGE L_xx where xx is the country code as listed in the file Locales.h.  Other languages can easily be added if you can do the translation though, so please ask on the forum to learn how to go about this.


There are other advanced settings in the Config.h file and those should all be left in their default state at this stage.  Once you have things working you can go back and customize to your liking.

Flashing The WiFi Server

The exact flashing procedure depends on which ESP8266 device you will be using.  From the Arduino IDE Tools->Board menu select the correct ESP8266 device:

For a WeMos D1 Mini, and WeMos D1 Mini Pro, or similar.

  • For flashing a WeMos D1 Mini through its micro-usb port : power off the OnStep controller, take the WeMos out, connect it directly to the PC using a USB cable, and in the Arduino IDE, select the "LOLIN (WEMOS) D1 R2 & mini" device from the boards list. 
  • 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 must be placed into firmware upload mode and connected to your PC.
    • Pin CHPD/EN must be HIGH (connected to 3.3V) Pin GPIO0 must be LOW (connected to GND).  You can buy an inexpensive USB adapter board that helps with flashing the ESP01 from eBay, Amazon and other sources.
    • The MiniPCB version 1 also has the ability to do this as detailed above using the :hF#:ESPFLASH# command.
  • 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"

You may now upload to the ESP8266.  Once done, power off OnStep and the ESP8266, wait a few seconds, then restore power.

Start Up Sequence and Connecting

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 its baud rate up to a higher operating baud rate of 57600 (or 19200 for a Mega2560.)

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 another 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.
  • Some Windows and perhaps other OS's can become confused for a while after the ESP8266 is restarted.  Windows seems to refresh SSID's and associated security information periodically (perhaps every 15 or 30 seconds.)  After an ESP8266 restart, the prior SSID and security information is NO LONGER VALID until the next refresh occurs and so any connection made before that refresh will not work.

Once It's Working

When you power on your OnStep controller you can connect to the Wifi add-on access point from a computer or 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.
  • You can also configure a password for the ESP8266 WiFi settings (on the WiFi web-page and saved in EEPROM) so it can't be accessed using the default "password".

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.

Other times we've seen cases where the background WiFi stack settings seem to interfere with the module starting up properly.  In these cases wiping all flash (and hence clearing those settings) seems to fix the problem.  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 cause of trouble is the flash memory chips on a given module not working with the selected flash memory mode (Arduino IDE selection of QIO, DIO, QOUT, or DOUT.)  I would provide guidance here if I could, but that seems to be impossible to do (manufacturers randomly use whatever flash chips the can get their hands on!) so you'll have to experiment.

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.