Load the firmware and connect to WiFi

Reading time: ~15 minutes · Execution time: 20-30 minutes · Audience: anyone who just finished assembling the controller following guide 02

🟢 Fundamental Guide — mandatory onboarding path. Without it, the system will not start.

🗺️ Your JoyReef Path:

1. Shopping list
2. Controller assembly
3. Firmware + WiFi ← YOU ARE HERE
4. Tank and sensor configuration
5. Tasmota smart plugs
6. Automations (ATO, etc.)

1. Before you start

For this guide you need:

• ✅ The controller already assembled as in guide 02: NodeMCU on the board, probe + display + float switches connected
• ✅ The micro-USB data cable (must pass data, not just power — see shopping list)
• ✅ A computer (Windows, macOS, or Linux) — not a phone, for this part you need a real PC
• ✅ Google Chrome or Microsoft Edge installed on the computer (Safari and Firefox do not work for loading firmware)
• ✅ A 2.4 GHz WiFi network available at home (modern 5 GHz networks from newer routers are not supported by the controller)
• ✅ A phone or the same computer, for the WiFi configuration step (later)

⚠️ 2.4 GHz WiFi is mandatory: the NodeMCU's WiFi chip (model ESP8266) does not support 5 GHz networks; it's a hardware limitation of the chip and cannot be bypassed. Most modern routers offer both bands simultaneously; if your router has them merged into a single network (a feature called "band steering" or "unified WiFi"), the controller might fail to connect. In case of problems, temporarily disable the 5 GHz network from your router's configuration page — the controller will find the 2.4 GHz one immediately. Once it's connected, you can re-enable the 5 GHz: the controller remains connected to the network it learned to join. If in doubt, ask your Internet provider.

2. Create your JoyReef account

Before loading the firmware onto the controller, you must have a JoyReef account: the portal is the "brain" that receives data from the controller and allows you to view it from any phone or computer.

Registration

1. Open portal.joy-reef.com in Chrome or Edge
2. Click "Register" in the top right (or go directly to portal.joy-reef.com/register)
3. Fill out the form: - Email: the one you will use to log in - Password: choose a secure one, at least 8 characters - Confirm password: same as above
4. Click Register

Email verification

Immediately after registration, the portal will ask you to verify your email:

1. Check your inbox (also check Spam/Junk — sometimes the first message ends up there)
2. Open the "Verify your email address" message
3. Click on the verification link

Once your email is verified, you are in: you will see the portal dashboard, currently empty — this is normal, it will receive data as soon as the controller is connected.

💡 Important: the email and password you just chose are also your controller's credentials. When you have to configure it (later in this same guide), you will use exactly the same data. You don't need separate "MQTT credentials" from somewhere else.

⚠️ Not receiving the verification email? Wait 1-2 minutes, check your Spam folder. If it doesn't arrive at all, you can click "Resend verification email" from the portal. If still nothing, write to us at supporto@joy-reef.com.

3. Load the firmware onto the controller

What is firmware? It's the software that runs inside the NodeMCU and "teaches" it how to read sensors, how to talk to the portal, etc. Without firmware, the NodeMCU is an empty board that does nothing.

Loading happens directly from the browser — you don't need to install any programs.

Step 1: open the flash page

Open portal.joy-reef.com/usb-flash in Chrome or Edge.

You will see two columns: on the left the requirements (all must be checked in green), on the right the list of available firmware.

🖼️ Image to insert here (/usb-flash page): screenshot of the portal page with all requirements checked and the "Install" button for the "Controller" firmware clearly visible.

Step 2: connect the controller to the computer

1. Take the micro-USB data cable from the shopping list
2. Connect one end to the NodeMCU (the micro-USB port visible on the board) and the other to the computer
3. A red or blue LED will light up on the NodeMCU (it's just a power indicator, nothing more: apart from this, nothing will happen until the firmware is loaded)

Step 3: start the flash

1. On the portal page, in the "Controller" section, click the "Install" button
2. The browser opens a small window asking you to choose a serial port
3. Select the one that corresponds to your NodeMCU. It's usually called "USB-SERIAL CH340", "Silicon Labs CP210x USB to UART", or similar. If you see multiple ports and don't know which one, disconnect the USB, see which one disappears, reconnect and select that one
4. Confirm "Connect"
5. The flash starts automatically — it takes about 2-3 minutes, you'll see a progress bar
6. When finished, the controller reboots by itself

⚠️ On Windows and macOS, you might need to install a USB driver if the browser doesn't see any serial port. Search Google for "CH340 driver Windows" or "CP2102 driver macOS" (they are free, download directly from the chip manufacturer's site). On Linux, it usually works without installing anything.

💡 "Connection failed" error at start of flash? Disconnect the USB cable, wait 5 seconds, reconnect and try again. Sometimes happens on the first connection.

4. Verify that the flash was successful

A few seconds after the flash finishes, the controller reboots by itself and the display should turn on.

What you will see on the display

1. For 2-3 seconds, the JoyReef logo appears, filling the whole screen
2. Then the setup screen appears, consisting of 3 lines:

WiFi: AP
AP: joyreef-XXXXXX
MQTT: ...

In place of XXXXXX, there will be your controller's unique code, for example joyreef-3f7a92.

🖼️ Image to insert here (Display in setup mode): macro of the OLED display showing the three lines WiFi: AP / AP: joyreef-XXXXXX / MQTT: .... Visual confirmation of "this is what you should see if everything works."

If you see this screen, the flash went well and the controller is waiting to be configured (next section).

What does "AP mode" mean?

The controller has created its own private WiFi network (called joyreef-XXXXXX): it's used to allow you to configure it because it doesn't yet know your home WiFi. It's a temporary network that will turn off as soon as you give it your router's credentials.

If something goes wrong

5. Connect the controller to your home WiFi

Now that the controller is in setup mode, you must:

1. Connect your phone (or PC) to the joyreef-XXXXXX network created by the controller
2. Open the configuration wizard in your browser
3. Enter your home WiFi credentials + email/password of your JoyReef account

Step 1: connect to the controller's network

From your phone (or PC):

1. Go to your device's WiFi settings
2. Look for a network called joyreef-XXXXXX in the list (XXXXXX = your controller's unique code, same as seen on the display)
3. Connect: usually no password is required

💡 The phone might warn you "Internet not available": this is normal. The controller is not yet connected to the Internet — it's waiting to be configured. On Android, confirm "Stay connected", on iPhone confirm "Keep connection".

💡 Disable mobile data before continuing: if the phone has both the joyreef-XXXXXX network and the mobile data network active, Android and iOS might automatically "prefer" mobile data (because they see the WiFi has no Internet) and make the browser open at their address instead of the controller. From the quick settings menu, disable mobile data for the duration of the configuration — re-enable them normally after the wizard has been saved.

Step 2: open the configuration wizard

Many phones automatically open the configuration page (this is the "captive portal" function, same as used in hotels, for example, when asking you to accept WiFi terms of use).

If the page opens by itself, skip to Step 3. Otherwise:

1. Open your phone's browser (Chrome, Safari, Edge — any will do)
2. Type in the address bar: 192.168.4.1 and press Go
3. You will see the JoyReef configuration wizard appear

🖼️ Image to insert here (Captive portal wizard): screenshot of the first step of the wizard ("Language" + "Timezone") seen from the phone.

Step 3: fill out the wizard

The wizard has 3 screens. Fill in and press Next at each step.

Screen 1 — Language and Timezone

• Language: English (or your preference)
• Timezone: Choose your timezone — fundamental, check that the automation and log times are correct later

Screen 2 — Your home WiFi

• WiFi: Select your home network from the list (it must be 2.4 GHz)
• WiFi Password: Your network's password
• Press Test connection: If the connection is successful, the Next button will appear

Screen 3 — JoyReef Credentials

• Username: The email of your JoyReef account (yes, the email, even if the label says "Username")
• Password: Your JoyReef account password
• Press Test connection: If the credentials are correct, the Save and Finish button will appear

Step 4: save and wait

Press Save and Finish. The controller then:

1. Saves the settings in its internal memory
2. Turns off the joyreef-XXXXXX network
3. Reboots and connects to your home WiFi
4. Connects to the JoyReef portal (you verify this in the next section)

Your phone will automatically disconnect from the controller's network (because it turned off). Reconnect your phone to your home WiFi for the next steps.

⚠️ If the WiFi connection fails (Screen 2): first, recheck the password. If that's not the problem, it's almost always a 5 GHz band issue: the controller's ESP8266 chip cannot see that type of network. Log into your router's configuration and temporarily disable the 5 GHz network (or separate the two bands by giving them different names). Try again: the controller will find the 2.4 GHz and connect. You can re-enable 5 GHz immediately afterward.

⚠️ If JoyReef credentials fail (Screen 3): recheck that they are exactly the same as for the portal. If you updated your password after registration, use the new one. If it's your first time using them, log into the portal from a PC first to confirm they work.

6. Verify that the controller is online

After saving the wizard, the controller reboots and connects to your home WiFi. You need to check two things: the controller's display and the portal.

Check the display

After 10-20 seconds from rebooting, you should see on the display:

WiFi: OK
IP: 192.168.1.42
MQTT: OK

The IP you see (instead of 192.168.1.42) is the address your router assigned to the controller. It changes from house to house, which is normal.

The three lines that matter:

• WiFi: OK → the controller is connected to your router
• IP: ... → it received a valid address
• MQTT: OK → it's talking to the JoyReef portal ✓

If you see everything OK, you're set.

Check the portal

On your PC (or phone, now reconnected to your home WiFi):

1. Open portal.joy-reef.com and log in
2. Go to the Devices menu
3. You should find your new controller in the list, with the name joyreef-XXXXXX (same code as on the display)

The first connection can take up to 1-2 minutes: the portal waits for the controller to send its first message before showing it.

🖼️ Image to insert here (Device in portal): screenshot of the /devices page with the newly registered controller in the list, showing a bright green "Online" badge.

If something goes wrong

7. You've connected the controller!

Well done, you've done the hardest part. From now on, everything is configured from the portal from your couch: no more USB cables, no more captive portals.

✅ System status right now: hardware ✓, firmware ✓, WiFi ✓, JoyReef account ✓, controller online on portal ✓.

What's missing to have a dashboard full of useful data:

The controller is already sending its sensor readings to the portal, but JoyReef doesn't know what they're for yet: is the DS18B20 probe "the temperature"? And of the 4 float switches, which one is "low level ATO" and which one is "safety level"? You need to tell the portal who is who.

📖 Guide 04 — Tank and sensor configuration (~10 min)

In that guide, you will create your first virtual tank, assign sensors to their reef-keeping functions (tank temperature, sump level, etc.), and see the dashboard populated with your live data.

Happy reefing!

JoyReef Guide · v1.0 · Questions? Write to us at supporto@joy-reef.com