From Uzebox Wiki
Jump to navigation Jump to search


This page is intended to be complete guide for everything ESP8266 related on the Uzebox using the Uzenet protocol. The page will cover all current standards and be updated as things change. With this guide you should be able to use most, if not all, of the different available hardware versions of the ESP8266 for Uzebox multiplayer or other internet enhanced applications. Anything not documented should be requested in the forums to enhance this page in the future.

What It Is

The ESP8266 is a low power(with good range), highly integrated Soc(System on a Chip), at extremely low cost, offering internet connectivity over a serial/UART interface. The device can connect to a wireless access point(AP) or even act as an AP that you can connect to with any WiFi device. Many different versions are available on the internet for less than 4€/US$5/C$6. Any version will work(currently expected) with a couple caveats for certain model(s) listed. The device is designed for 3.3 volt supply and logic levels and is capable of up to 4 discrete internet connections to any place in the world over TCP or UDP protocols. It is operated using the ESP8266 AT Commands which the Uzebox uses to create the desired setup and data transfers which creates the Uzenet protocol. It is available from many different places:

Site Link Notes
AdaFruit [1] more expensive but they are friends to Uzebox
AliExpress [2] As low as US2.69$ with free shipping.
Ebay [3] larger quantities available at discount
Olimex [4] fast shipping, good price and packaging
BangGood [5] to your door for < $4 [6] best source for development information, donate to receive modules and support the cause.
Seeed Studio [7] the author is biased against this one

and many more.


This is the schematic for standard Uzebox:


It is important to use a 3.3v voltage regulator as described, 5v to VCC or CH_PD or RST has been proven to damage the chip. These are the available pinouts for different versions of the chip:


For the correct connection for any model refer to the pinout to find the individual name pins and connect in this manner:

ESP8266 to Uzebox
VCC (3.3v, IMPORTANT!) 3.3v regulator as per schematic
GND(-0v) GND
CH_PD (3.3v, IMPORTANT!) 3.3v regulator/bridge to 3.3VCC
RST(3.3v) PD3(gets grounded to reset)
RX(3.3V) (*direct 5v logic works) TX
TX(3.3V) RX

UPDATE by UZE as per the ESP8266 datasheet, all I/O pins are protected against ESD and overvoltage (see p.15). This implies I/O pins are 5V tolerant and should not require voltage divider or level shifters. BUT, it should still be powered with 3.3V. I have a ESP-01 running non-stop for many days now without any issues. I will test more versions and report over time.

Upgrading Firmware

Check out the ESP8266_Manual_Upgrade

The '8266 can accept new firmware flashed to it that can fix bugs, add AT commands, or even a program to run the device standalone using the onboard MCU. Different versions of the device will come with different versions of the firmware from the factory. Some newer devices may support firmware upgrade over wifi or OTA(Over The Air) while others will require manual pin connections to complete the upgrade. Once an upgrade to an OTA compatible firmware is completed there will be no need for manual intervention in the future. You can connect your device using a USB->Serial adapter(must be 5 volts TTL dont use a 'real' serial port! Don't connect those 5v to anything but RxTx!), FTDI, or an Arduino Uno works nicely and is probably available at your local electronics store. Using some devices might require using an external power supply should it not be able to provide enough current. Arduino UNO(3.3v on board) does have enough even when powered by USB only, but you must use 3.3v for VCC and CH_PD.

Once you have connected the device to a serial adapter of some sort and plugged it into your PC, you can open up a terminal emulator of your choice(PuTTY, Arduino monitor,etc). Different versions of the firmware will default to different baud rates in the terminal so it is possible that you will see gibberish displayed from the device. If this is the case you will need to experiment with different speeds until, after a fresh power cycle, it displays some giberish then "OK" to indicate it is operational and you are running the right speed to receive the characters correctly. Common default speeds are 115200, 57600, 9600 etc. You can check your firmware version with "AT+GMR" and experiment with manually using the AT commands. In newer versions you will be able to change baud rates at will without a reset.

Once have verified your device is setup and working correctly over a serial connection it is time to get our new firmware we will need to enable OTA updates. This *FILE TO BE ADDED* archive contains a working flasher and firmware file that will bring your device to an OTA ready state. You can also check here[8] for newer versions. Before you can use the program you must put the device into a state that is ready to receive new firmware. This is accomplished by grounding GPIO0 and momentarily grounding RST. Once the device boots back up with GPIO0 still held low, it is awaiting for a firmware file over the serial interface. Simple open the program, select your COM port for the serial device, select the firmware file you want to flash and click program.


The process will take about 1 minute to complete, and may indicate an error has occurred at 99% but the firmware will be intact. If everything went well you should be able to do another "AT+GMR" and see that your version is now newer. If everything went really well you should now be able to do "AT+CIUPDATE", after manually using AT commands to setup the network connection. Let's take a quick look at how to do that:


To make this guide more concise AT commands will not be thoroughly discussed and on purpose only enough explanation to achieve a compatible firmware for Uzenet will has been discussed. The reason it is important to use the standard firmware version provided is that the AT commands must be exactly right or Uzenet will not work or have issues. For whatever reason, even the basic commands have several nuances different across versions.

If you are having trouble with this step check out some other tutorials on the net like these:[9][10][11][12][13]

Uzebox Setup

Now that you have made your ESP8266 Uzenet Ready you will need to configure it to connect to the internet. You must of course have a wireless access point("wifi router") that has an internet connection to play online. Preferably this connection will be high bandwidth with low latency. Satellite or Cellular internet connections might still work for slower paced games, but latency is critical for any "reflex" game and people might not want to play with a lagger ;)


To setup your device for the first time after properly connecting and upgrading it you will need this rom image[mythicalrom.hex]. Once you have started the program on your Uzebox it should start and give an indication that it is successfully communicating with the device. If an error is given, go to the troubleshooting section to diagnose the problem. The program will display a list of all the wireless APs that it can detect. If you had previously setup a device you will be given the option to connect to the last configured connection and bypassing connection settings. Otherwise you will need to more your cursor onto the name of the AP you want to connect to and click the START button. Now a menu will appear asking you to enter the password for the AP. If there is no password leave it blank otherwise use your cursor and the B button to enter each character of the password and press START to connect. If everything went well you should be shown a message that the connection was sucessful. At this point you are done and can start using Uzenet enhanced features such as multiplayer games, chat, rom downloads, and perhaps a streaming MIDI service. The settings will be saved in the device itself so next time you apply power it should automatically connect. It is possible over a couple weeks without power you would need to reconfigure again but luckily the settings from last time will be saved to EEPROM. If you receive an error in game and can't get online just run the setup program again.

Emulation On PC

TODO emulation using a PC program that interprets serial commands into a sockets enabled state machine should be possible for someone to directly connect Uzebox->USB serial cable...

Trouble Shooting

I am having problem X what to do?

The first and easiest thing to do is run the setup program again to make sure everything is working correctly. Otherwise the error codes it gives could help in diagnosing the problem.