IoTBox: Instructions for use

When power is applied to the IoTBox, it will try to connect to the stored WiFi access point and will show the IP address on the screen if successful. The screen will show an error message if it cannot connect.

The IoTBox uses two WiFi modes simultaneously:

  1. Client Mode = It will connect to an Access Point.
  2. Access Point Mode = It will behave as an Access Point.

To configure the IoTBox, look for an open network with the same ID as shown on the OLED display, it will be similar to “iotbox00fcf9ab”.

IoTBox MenuWhen connected, your PC/Mac or Phone will have an address of and the IoTBox menu will be found at

The first thing to do is to upgrade to the latest version of the WiFi SettingsIoTBox firmware. For this, you will need to be connected to an external Access Point chosen on the WiFi settings page and then select OTA Upgrade. The IoTBox will download the updated firmware and then reboot into the new version.

The ESP8266 on the IoTBox is configured as two slots. The OTA firmware is downloaded and stored in the other slot. If it has downloaded correctly, it will reboot into the other slot. You may switch back to the old version by using the Switch ROM menu option.

If you have configured something that is causing an issue with the IoTBox, you can reset it using the button (wired to GPIO0). The button on the IoTBox has three functions:

  1. If the button is held down while powering on, you can update the firmware on the chip with a programmer. This is only required when putting the initial firmware on the chip.
  2. If the button is pressed for more than 0.5 seconds and less than 10 seconds (2 seconds is ideal), a message is sent to the button MQTT topic.
  3. If the button is pressed for more than 10 seconds, the settings are cleared to the default values. You will need to set the WiFi and MQTT parameters again.


MQTT Topics

IoTBox has an MQTT v3.1 client built into the firmware and is the main way of communicating to other systems. When MQTT is enabled, it will try to connect every 10 seconds and when successful, it will post “online’ to the LWT topic.MQTT Menu

The following topics are supported:

Note: MQTT can use wildcards, such as ‘+’. This means that a subscription to ‘+/out/led/1’ will pick up data for ‘iotbox00112233/out/led/1’ and ‘iotbox56229922/out/led/1’. This is useful when sending  the same information to many devices.

LED: For the example shown above, the IoTBox is listening on:

  • +/out/led/1
  • +/out/led/2
  • +/out/led/3

A payload of ‘0’ or ‘1’  to these topics switches the LED colour (red, green or blue) off or on. This will likely change in the future to support PWM and a single Topic.

DISPLAY: For the example shown above, the IoTBox is listening on:

  • +/out/display/0
  • +/out/display/1
  • +/out/display/2
  • +/out/display/3
  • +/out/display/4

A payload of upto 20 characters will be displayed on lines 3-8 on the OLED screen. Useful for notifications and information.

BUTTON: A button press creates a payload of ‘1’ on the Topic.

TEMPERATURE: Readings from the sensor (DS18B20 or DHT22) are sent every 10 seconds to this topic.

HUMIDITY: Readings from a DHT22 (if connected) are sent every 10 seconds).

LAST WILL & TESTAMENT: When the IoTBox is connected to MQTT, a payload of ‘online’ is sent to this Topic. The MQTT server will send ‘offline’ if it does not receive a heartbeat from IoTBox.

The best way of exploring how IoTBox uses these Topics is to use the MQTT-SPY application found at MQTT-SPY Homepage.

11 thoughts on “IoTBox: Instructions for use”

  1. Hi
    Maybe something stupid but..
    I did an OTA update and now ESP AP asks for a password. I’ve tried entering my SSID password and also reflashed but am not able to connect to config page.

    1. If you have flashed to a new version that has new parameters, sometimes it has to clear the previous settings so it returns to the default settings. The defaults do not include a password for the login in page on the esp – so thats strange!.
      To clear the settings back to defaults – just press the button (Ground GPIO0) for more than 10 seconds.

      Hope that helps

  2. Hello
    mqtt host setting keeps defaulting to and refuses to retain my input after reboot. I am testing on an ESP-01, would that be an issue?

    1. ah – that could be a problem. The mechanism for updating requires the larger flash size of (most) ESP-12 and 12e. It splits the flash in two sections and the update overwrites the second section and then reboots into it. The settings are common to both sections.

  3. Tony
    I now have a board with an on board ESP-12 and am having the same problem ie unable to update and retain settings. You mentioned that “most” ESP-12s have larger flash size. Do I have a rogue one? How can I tell? On another note I had problems burning the firmware until I grounded GPI15.

    1. ah, I bet I know what the problem is!. I had a similar query from another IBM’er. In his case it was due to memory size not being set correctly by the flashing software.
      How are you flashing the chip?. We solved his problem by using the flasher here:-
      With these addresses:
      Address Code
      0x00000 rboot.bin
      0x02000 iotbox.bin
      0x80000 iotbox.espfs.bin
      Try it with the SpiAutoSet function enabled to see it correctly gets the 32Mbit chip size. If not use these settings:
      Crystals 26M, SPI Speed 40MHz, SPI Mode QIO, Flash Size 32Mbit

      Let me know how you get on!

  4. Hi some success. I tried a third ESP-12 which accepts updates. The first 2 I bought from the same source and they must me dodgey!
    I have designed a little board for this. I used the toner method and etched it. PDF for anyone who wants it.

  5. All working now. Great project.. some confusion though over the led. I’ve wired it red-gp15, green-gp12, blue-gp13 as per instructions.
    Using Mqtt I get
    led 1 green
    led 2 blue
    led 3 red
    Using the web config page I get
    blue – green reverse.

    1. Thanks John – great that you have it working now. The latest version of the firmware is v2.4 (as of today) which corrects a problem if IoTF mode is chosen and the wifi access point is not available.
      You can OTA update from the menu. Thanks for RGB pinout reminder!. The original board was wired slightly differently but I changed it so that I could mount the LED on the back of the adaptor to fit nicely in my case.

Leave a Reply

Your email address will not be published.