Last edited · 47 revisions  


Smart Web Server (Ethernet and WiFi)

This OnStep has an software addon called the Smart Web Server (SWS,) it works with certain hardware to provide WiFi or Ethernet connections to OnStep over IP.  Many devices support this type of connection including cell-phones, tablets, laptop/desktop computers, etc.  The SWS has both a web-server and standard IP command channel (on port 9999) which programs such as Sky Safari, my ASCOM driver, and the Android App can use simultaneously.  WiFi also 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 ESP32 and Teensy's will be faster and in the case of the Teensy4.0/4.1 the count limits are expected to be very high indeed.  All of the "Max" designs in the Wiki bring out encoder connections on their DB9 or DB15 connectors.


We've largely standardized on the WeMos D1 Mini "footprint" for the WiFi and Ethernet addon.  Both the ESP8266 and ESP32 are available in pin compatible form so they can plug into the same socket.  With the ESP32 you also have the possibility of adding the Bluetooth GamePad Controller.  Even the Teensy3.2 and Teensy4.0 with W5500 Ethernet (USR-ES1) can be built into a WeMos pin compatible module using a custom PCB. All of the "Max" designs in the Wiki can utilize this board as it positions the Ethernet jack so it neatly passes through a cutout in the case side.

Below are some of the options available to fit in this socket:

---WeMos D1 Mini--- --WeMos D1 Mini Pro-- ---ESP32 TTGO T7    --- ----Teensy/W5500 Ethernet----


Note that the MiniPCB2 lacks the extra space around the WeMos socket to use the above ESP32 for WiFi or Teensy/W5500 for Ethernet.  Also, the only custom OnStep board that doesn't require or recommend the WeMos form is the MiniPCB Version 1 which uses an ESP8266 (only) ESP-01 module due to it's smaller size.

For Ethernet, using the Arduino Zero with W5100 or W5500 shield (eBay has clones) is an easy option for users with 3D printer boards like the MKS Gen-L, ESP32/CNC3, or S6 where a WeMos D1 Mini socket isn't present.


  • The WeMos D1 Mini (ESP8266) is the most tested device.  The Teensy3.2 w/W5500 is the second most tested.  The ESP32 "TTGO T7" has also seen a fair bit of use and is probably a safe bet.  Other combinations should work in theory but do not have extensive testing.
  • There are several versions of the ESP32 D1 design that will work. These include the TTGO T7 V1.3 or higher, MH-ET Live D1 Mini ESP32 and Mini D1 ESP32 Wemos. These are all pin compatible with the WeMos D1 Mini (ESP8266). Many other versions of the ESP32 will also work but will have a different pinout and module footprint.

Installing the ESP32, ESP8266, or Teensyduino Platform

Before you can flash the firmware on your ESP8266, ESP32, or Teensy device, you need to install the platform for the Arduino IDE.  This step is covered during OnStep installation but please double check that the Arduino IDE is setup as required for Uploading the Firmware to the WiFi or Ethernet hardware as well.

Getting the Smart Web Server Firmware

Unless the Wiki instructions for your particular board states otherwise, it is recommended that you use the latest Smart Web Server release.  Follow this link for the SmartWebServer to GitHub and select the "Code" button, and choose "Download ZIP".

Unzip the folder to your PC. This can be on your desktop or in your ~/Documents/Arduino folder.

The directory will be named "SmartWebServer-main". You must rename the directory to "SmartWebServer", otherwise you will not be able to compile properly.  Double clicking on "SmartWebServer.ino" will then open SmartWebServer in the Arduino IDE (if everything is installed correctly.)

Preliminary Firmware Configuration


For most boards no changes to OnStep's Config.h file are required though there are exceptions.  Please refer to the Wiki page for your hardware and its section on "WiFi, Ethernet, and Bluetooth" for any Config.h changes that may be required depending on your hardware design.

Smart Web Server

No changes to the SWS's Config.h file are required for it to function properly.  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 "en" or "de". 

  • Tips:
    • Other languages can easily be added if you can do the translation, please ask on the forum to learn how to go about this.
    • There are other advanced settings in the SWS 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.

Uploading the Firmware

After you have done the above, proceed with the uploads.

For setting up OnStep follow the Uploading the Firmware guide.

For the WiFi or Ethernet device, first unplug it from its OnStep controller (completely,) then plug into your PC via its onboard USB port and do the following:

  • In the Arduino IDE Tools menu select the correct board and port.
    • The ESP32 comes in many types but the ESP32 Dev Module using its default settings generally seems to work for the variants we use.
    • For any WeMos D1 Mini ESP8266 use the LOLIN (WEMOS) D1 R2 & mini and its default settings.
    • For the ESP-01 ESP8266 module (MiniPCB v1) use the Generic ESP8266 Module and the following settings (for others use defaults):
      • Flash Mode: "DIO"
      • Erase Flash: "Sketch + WiFi Settings"
      • Flash Size: "1M (64K SPIFFS)" (Most ESP01 have 1M, older ones have 512K)
      • Reset Method: "ck"
      • Upload Speed: "115200"
  • Where the operating frequency can be changed I always use the default (not overclocked.)
  • Where the compiler optimizations can be changed I use Fastest (but NOT with LTO.)
  • For these boards additional options in the Arduino IDE Tools menu need to be set and/or additional steps taken to upload:
    • For the ESP32 the Boot button on the module may need to be pressed for > 2 seconds to allow firmware upload.
    • For the ESP-01 ESP8266:
      • For flashing through the OnStep controller:
        • 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 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.
        • ESP8266 firmware 2.4.2 is the only known version to work for this.
        • This will only work if support is enabled in OnStep and physical connections to the modules GPIO0 and RST pins are present.  This is covered in the MiniPCB v1 Wiki.
      • You can buy an inexpensive USB adapter board that helps with flashing the ESP01 from eBay, Amazon and other sources.  Plug the ESP-01 into that board and flash across USB

Once done, power off OnStep and the addon, wait a few seconds, then restore power.

Start Up Sequence and Connecting

OnStep and the addon both use a default serial port baud rate of 9600.  On startup the addon attempts to contact OnStep on two ports, the main and alternate (ESP8266 swapped.)  During the connection attempt, the WIFI addon device LED will flash repeatedly.  Once it gets a valid responce it causes the LED to illuminate continuously and sends a command to OnStep to change its baud rate up to a higher operating speed of 57600 (or 19200 for a Mega2560.)

The web server and command channel will only start if the addon 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.  For WiFi capable devices you will not see the OnStep (etc.) SSID unless the connection succeeds.


  • During this time you might notice repetitive flashing of the SWS devices serial activity 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.)
  • If the SWS device has a status LED (properly configured) that will also flash when trying to connect and will remain solid ON if successfully connected.
  • You can change the default and operating baud rates of BOTH OnStep and the SWS device 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 more quickly.
  • You can also force the SWS to attempt to connect on a specific port location (standard or swapped) instead of trying both over and over:
    • For both:
      • #define SERIAL_SWAP AUTO
    • For standard location only:
      • #define SERIAL_SWAP OFF
    • For swapped location only:
      • #define SERIAL_SWAP ON

Once It's Working

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

  • For WiFi, first connect to the WiFi SSID "OnStep", the default password is "password".
    • On the Network webpage you can change the SSID, IP address, switch from Access Point to Station Mode, change the passwords, etc.
    • The default is Access Point Mode with an IP address is
  • For Ethernet make sure the IP address matches your LAN then plug in.
    • On the Network webpage you can change the IP address, subnet, change the password, etc.
      • The default IP address is
  • Open a browser, and enter the above IP address to reach the website.  Or open Sky Safari, the Android App, my ASCOM driver, etc. and use above IP address followed by :9999 for an command channel connection (for example

Flashing Trouble

Many users report problems getting the modules to flash and operate, mostly this applies to ESP8266's, and the following tips have helped in some cases:

  • Repeatedly flash the module 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 poor quality flash memory is the suspect.
  • 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 or ESP32 (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.

  • For the ESP8266 there is an Arduino IDE option to clear the flash memory and so reset everything to 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.
  • For all devices the settings in NV (EEPROM, etc.) can be erased by setting the ConfigX.h option #define NV_WIPE ON and upload, wait a minute or so, then turn the option back OFF again and upload again.
    • Tip:  Be sure to read the warnings about using this option in the ConfigX.h comments.

Wireless Networks and Advanced Configuration (warning: long)

A wireless network is created by an access point with a given SSID (Service Set IDentifier). The access point manages the subnet's IP address range and allows devices connected to the subnet to communicate with each other. Think of an access point as the hub of a local WiFi subnet.

In its default configuration, the SWS creates a subnet with the SSID of 'ONSTEP' with a password of 'password' on WiFi radio channel 7. There are valid reasons for changing that which we'll get into in a moment. Also by default, the ONSTEP network uses the IP address range 192.168.0.x where x can be from 0 to 255 (the addresses with x=0 and x=255 are reserved for special uses and, by default, the SWS claims for itself). Again by default, SWS access point mode has DHCP (dynamic host control protocol) enabled which means that SWS will assign an IP address to a device as it connects rather than have the device insist on using a particular address. DHCP enabled is what most users will want because it eliminates the requirement to manage addresses yourself and the possibility of conflicts. With DHCP, your device doesn't really need to know its own address anyway - all it needs to know is the fixed address that SWS itself uses.

This is the network setup described previously and will be the network everyone should get using the software with unchanged configuration files after they have been successful in connecting the WiFi hardware module to the controller. This is a good place for new users to start because it is a standard configuration that will always work and will be easy to get group assistance if there are difficulties.

Many users can continue to operate this way indefinitely with no need to make any network parameter changes.

However, there are valid reasons to change some of the default access point parameters. If you are in an area with a number of other wireless networks, it is possible that some of those will already be using channel 7 and this could cause reduced reliability on the SWS network due to interference. There are a number of WiFi analyzer apps available for phones and tablets that can display the channel usage in the area and help you pick a more interference-free channel. Also, if you anticipate going to an area with multiple OnStep users (e.g. a star party) it might be best to personalize your SSID in advance so that there is no confusion about which one is yours. Additionally, its always a good idea to change the both the access point and administration passwords so that no one else can connect to your system and make it do strange things, either accidentally or on purpose.

Now most users will be familiar with the access point created by their home router but the difference between it and the ONSTEP access point network created by the SWS is that the SWS does not have an uplink router (or the capability to attach to a router with uplink capabilities) in order to route packets to wide area network for internet access. This is the reason that, after connecting your device (PC, tablet, phone) to the SWS access point, the device loses the ability for concurrent applications to access the internet.

SWS has a solution for that... its called 'station mode'. In this mode, SWS will connect to an already existing WiFi network with internet uplink routing such as your home router in the same way that your PC, tablet or phone does. The benefit to station mode is that applications on your device will be able to connect to SWS to control your OnStep mount and connections to the internet are possible at the same time. You just have to enter the SSID and password to your home network's router's access point and enable station mode.

The only issue with station mode is that most home access points have DHCP enabled by default which SWS will use to receive its IP address on that network when it connects. You would have to know what address it got before you can connect to the SWS. You can do this by logging into the administration portal of your router and searching for it, usually by MAC address, in the list of connected devices. However, since the assigned address could change between one connection and the next, it would be better to have a constant IP address. This can be done in one of two ways: a) continue using DHCP on SWS but create a DHCP reservation in your router so it will always assign the same IP address to the SWS or b) turn off DHCP in SWS station mode setup and assign the IP address manually in a way that does not conflict with any existing or future device that will connect to your router using DHCP. If option b is chosen you will also have to enter the Gateway and Subnet mask manually.

Both station mode and access point mode can be enabled simultaneously. If SWS cannot connect to your home network, it will automatically start the access point network even if it is not enabled in the configuration. This is intended to be a fallback mode for people who normally operate their telescope in an environment where they want the controller to join their home network (so that devices that connect to the controller can still access the internet) but sometimes set up in 'away' locations. In this case, the access point wouldn't be cluttering the airwaves at home but would automatically come up when out of range of the home network where there is no internet connectivity to maintain anyway.