04 ‐ Onboarding and First Time Setup
If the controller has never been set up or if the controller is reset, you must onboard the controller to your WiFi and specify a few starting settings. It is recommended this step be completed before installing the ESP32 into the controller assembly.
You will need a mobile phone or other device (e.g. tablet, laptop) that can join an ad-hoc WiFi network. Two independent devices will be needed if you want to join the controller to a WiFi hotspot being broadcast by one of these devices.
The following examples will show an Android phone, but the process should be similar on an Android tablet or Apple iPhone/iPad.
You should be in the near vicinity of the controller for the onboarding process. Power up the ESP32 with the firmware installed and open the WiFi settings on your mobile device.
You should see a WiFi access point called “RaceTimer_AP”. If you do not immediately see this access point, wait a few minutes and make sure you are within 10’ of the controller. Restart the controller again if the AP does not appear.
Join this AP with your device. You may be warned that the AP does not have Internet connectivity. If prompted, select to remain connected to this AP.
You may also be prompted to “log in” to the new WiFi. If so, it should open your browser to the onboarding page. If not, simply open a browser and go to the IP address:
http://192.168.4.1
Enter in the WiFi name (SSID) and password for your wireless network. See the special note below if you want to join a hotspot being broadcast by this or another device. Then enter the specific information for your installation:
Device Name: Each controller on a given network must have a unique name. This identifies the device on the WiFi, is used for OTA (over-the-air) updates and is also reflected on the web settings page so you can assure you are working with the correct controller in a multi-controller situation. You can use something like Timer-01, Timer-02, etc. but the device name should only use letters, numbers and the hyphen (-) and must be 16 characters or less.
Number of LEDs: Enter the exact number of LEDs from one side only in your install. If you have identical matching LED strips on each side of the track, the LED signal is split and sent to both strips simultaneously. For this reason, you should only enter the number of LEDs on one side only. If the two sides have a different number of LEDs, use the larger of the two numbers. There is an upper limit of 500 LEDs for this project. If you are not using LED strips, or wish to disable their use, simply enter zero (0) for the number of LEDs.
LED Brightness: Set a starting LED brightness value from 0 - 10. This can be changed via the settings page after onboarding, but it is recommended that you start with a value of 5 or less. The LEDs will likely be brighter than you expect. Note that entering a value of zero effectively turns the LEDs off. This is different from disabling the LEDs by using zero for the number of LEDs. When brightness is set to zero, all calls to the LEDs still occur but with a brightness of zero (off). When disabled, calls to the LEDs are simply skipped.
Max Milliamps: As a safety precaution to prevent the LEDs from pulling too much current, enter a maximum milliamp value here. This should not be higher than around 80% of the rated capacity for the power supply. For example, with a 10A power supply, a max value of around 8000 should be used here. There is a minimum value of 2000 (2A… but small power supplies should only be used when disabling the LED functionality). This is also a maximum permissible value of 15000 milliamps (15A).
Once you have entered all values, click the Submit button.
The controller will automatically reboot and you will receive a message that the device is attempting to connect to the WiFi you specified. Watch the ESP32 controller at this point.
When first powered on, the red LED on the ESP32 will light solid. If the controller successfully joins the WiFi, the blue LED will blink three times and then remain solid.
If the ESP32 does not appear to join the WiFi (blue light doesn’t blink/remain solid), then use your mobile device to check and see if the RaceTimer_AP hotspot is still being broadcast. If this hotspot is still available, it means that the controller failed to join the WiFi and has reverted to broadcasting the hotspot. Join this hotspot again and repeat the onboarding steps above, assuring that the WiFi SSID and password are correct (these are CASE-SENSITIVE). If you still have issues getting the ESP32 to join your WiFi, see the troubleshooting section of the Wiki.
Once your controller has successfully joined your WiFi, you will need to know the IP address of the controller to reach the web settings page or to otherwise interact with the controller for options like rebooting, flashing updated firmware, etc.
Starting with version 0.25 of the firmware, the timer display will briefly show the IP address, one segment at a time during the boot process:
The above example shows an IP address 192.168.1.229. If you miss the IP address, simply reboot or power cycle the controller to get it to display again.
You can also normally find the IP address assigned by visiting your router web interface. Your router’s interface may look different from mine:
If your router recognizes the hostname, then you should be able to easily find your device and its IP address by just searching for the device name you gave it. As you can see above, this is my second controller (named RaceTimer02) and has an IP address of 192.168.1.217. There is another system, RaceTimer01, that I initialized to my WiFi earlier… and it has an IP address of 192.168.1.232.
Now with the IP address, launch a browser on any device (phone, tablet, computer) that is on the same WiFi network to see the settings page and to make changes. See Using the Web Interface and Settings section for details on using the settings.
Starting with release v0.22, a valid WiFi connection is required for the system to function. But what if you are using the system in a location (like a school for example), where WiFi is not available or it is a corporate/enterprise network and you are unable to use a simple UserID/Password to join?
If you have two mobile devices capable of broadcasting a WiFi hotspot, you can use this hotspot for the device's WiFi, although the initial onboarding is just a bit more tricky.
Two devices may be required to onboard the controller because a device may not be able to broadcast a mobile hotspot and also join a wifi network at the same time (I was able to do this using a Samsung S24, but unsure if this will work with older Android or Apple devices). For onboarding, the hotspot must be broadcasting and you must also be able to join the temporary hotspot being broadcast by the controller. This may be easier with two devices, or necessary if your phone cannot broadcast a hotspot and join the controller’s hotspot at the same time.
Device 1: This is the device that will be broadcasting the mobile hotspot/WiFi network for the controller. Start this device and begin broadcasting the hotspot.
Device 2: This is the device that will be used to join the controller’s hotspot (RaceTimer_AP) and complete the onboarding. Follow the normal onboarding process above using this second device.
Once the controller has rebooted and successfully joined the hotspot/WiFi (indicated by the solid blue LED on the ESP32), you no longer need the second device or can also join this second device to the mobile hotspot/WiFi to access the controller’s settings with this device (you can use the first device to access the settings as well).
Getting the IP Address when using a Hotspot
You will still need to know the controller’s IP address to access the settings page. However, since the controller is using the phone’s hotspot, the IP address won’t be in your router. Instead, you'll need to get the IP address from the phone itself. The method of doing this will vary greatly depending on the version of Android and/or if it is an Apple device. Check your device's documentation or search online for how to determine the IP address of hotspot-connected devices.
Special Note on performing firmware updates
While you can use a mobile hotspot for changing the settings and even restarting or resetting the controller, the one thing that you should NOT do when tethered to a mobile hotspot is a firmware update.
First off, you will need to have access to the new firmware file (.bin) somewhere on the local network for uploading. When connected to a mobile hotspot, this means that the .bin file would need to be copied to the local phone and be accessible. You also do not want any “interruptions” during the upgrade process. For this reason, it is recommended that you join/rejoin the controller to your normal WiFi network when doing firmware upgrades. Note that you must do a controller reset to change WiFi networks. This is covered under Using the Web Inteface and Settings section.
A no-WiFi version of the firmware was available prior to release v0.22. If you truly need a non-WiFi version and are unable to create/use a local hotspot as described above, you can download and flash the RobotCarTimer_v0.21_ESP32-NoWiFi.bin firmware. While most of the functionality is present in this version (but newer features added in later releases may be missing), the following will not be available:
- Settings and Options Page: Initial settings and all future options or settings changes must be done by editing the source code, compiling and uploading via USB.
- OTA Updates: With no WiFi, over-the-air updates (firmware and Arduino OTA) are not available. Firmware updates or each change to the settings will require flashing the updated code via USB connection.
- New Features: Obviously no new features added after v0.21 will be available.
Obviously, no onboarding is needed (or available) with the non-WiFi version. However, you must edit the source code for the initial settings and each time you want to make a change, followed by compiling and uploading. This could be especially challenging during some operations like fine tuning the sensors, which will likely require numerous trial-and-error changes.
Unfortunately, it is simply too time-intensive to try to maintain two independent versions of the firmware. Therefore, starting with release v0.22, only the full WiFi-required version will be supported. If you want the new features added to the non-WiFi version, you will need to fork or clone the repository and make those changes yourself. More info on editing the source code can be found in a separate Wiki topic.