Digistump Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Loading Firmware over Serial ======


**Firstly, a word of warning!!** Serial uploads always go to memory slot 0 of your Oak - no matter what is in that slot. A factory Oak boots to 0 looking for the system firmware, so if you upload via serial, you essentially wipe the ability for your Oak to do natively do OTA updates and firmware updates. If you want to restore that ability, you'll need to use follow the instruction on [[https://github.com/digistump/OakRestore|how to restore your Oak to factory defaults]].

====== Configuring your computer ======
In order to talk to the Oak over Serial, you may need two pieces of software installed (in addition to the Arduino IDE with appropriate Oak board support). The first is Python, and the second is the PySerial module for python. If you are using a Mac or Linux computer, is is very likely Python is already installed. If you are using Windows, then you will need to install it. In either case, you will also need to install the PySerial library to allow communication with the Oak.

===== Install Python on Windows =====
To install Python on Windows, download the installer from [[http://www.python.org/getit/]]. You'll want the 2.xx version (2.7.11 at the time of writing) as due to some changes in the Python syntax, using Python 3 will result in error messages.

{{ :oak:tutorials:python_windows_add_path_install_option.png?200|}}
When you get to the Customise step of the installation, make sure you scroll down and choose to install the 'Add python.exe to Path' option, as it is not done by default, and is needed so that the Arduino IDE can find Python when it needs to. A screenshot of the option in question is on the right - click it to get a larger view. If you miss this step, and get errors about not being able to find Python, you will need to add the python install folder to the system path.How you do this varies from version to version of windows, but you can usually find it by typing 'system environment' on later versions of Windows, or looking under System Properties in the Control Panel on earlier versions. It's probably best if you do a web search for something like 'how to add python to path' if you are unsure.


===== Install PySerial =====

Regardless of your operating system, it is fairly likely you will need to install PySerial, which allows Python to access your computers serial ports. You can start by downloading it from [[https://pypi.python.org/pypi/pyserial]]. On Windows, you can download the windows install, for other operating systems you will need the source file (pyserial-3.0.1.tar.gz at the time of writing). When I installed it on Windows 10, I got some error messages from the installer, and got rid of them by running the installer again as an administrator (right click on the installer and choose 'Run as Administrator'). 

If you are using a Mac or Linux computer, then open a Terminal session, 'cd' to wherever you downloaded pyserial-3.0.1.tar.gz and then issue the following command to unpack the installation folder.

''  tar -xzf pyserial-3.0.1.tar.gz'' 

Then “cd” into the pyserial-3.0.1 folder, then run the command:

''  sudo python setup.py install''
  
You should then be configuring things!

====== Connecting Your Oak ======

To program your Oak over serial, you will want to connect the GND of your USB-Serial Adapter to the Oak's GND, RX to TX, TX to RX, and P2 to GND. You can then power the Oak via the on-board MicroUSB slot, or by providing appropriate power to the VIN or VCC pins. This is probably a good time to also ensure that you [[https://github.com/digistump/OakRestore|reset your Oak to factory defaults]], so that it runs your program when you upload via serial (by resetting the bootloader to running the program loaded in slot 0). If you can't or don't want to do that, you can instead use the esptool command to at least reset the bootloader : 

<code>
esptool --baud 115200 --port YOUR_COM_PORT write_flash -fs 32m 0x1000 blank.bin 0x101000 blank.bin 0x102000 blank.bin 0x202000 blank.bin
</code>

//Needs pic of an adapter here, and some more detailed explanation of pin connections//

====== Programming via the Arduino IDE ======

{{ :oak:tutorials:arduino_ide_serial_upload_selection.png?100|}}
You will need to change your Upload settings in the Arduino IDE (under the Tools menu) from "Particle OTA" to "Serial (Expert Use Only - Requires Python)", and make sure that the Port settings is set to the right serial port. Click on the image on the right to see a screenshot demonstrating where these options are. As you can see in the image, I am still in Particle OTA programming mode at the time the screenshot was taken, and the Port menu is dimmed out as a result. It will become available for use once you change to the Serial upload mode.

When you upload your program to your Oak, you should see a message in the compile/upload log at the bottom of the Arduino IDE displaying the following message. If you scroll that view, you should see the percentage increasing as the program is being transferred to your Oak. 

<code>
Connecting...
Erasing flash...
Writing at 0x00002000... (0 %)
Writing at 0x00002400... (0 %)
Writing at 0x00002800... (1 %)
</code>

It should also have a end message similar to the one shown below:

<code>
Writing at 0x00041000... (99 %) 
Writing at 0x00041400... (100 %) 
Wrote 260096 bytes at 0x00002000 in 25.7 seconds (81.1 kbit/s)...

Leaving...
</code>

//And what next?//

====== Troubleshooting ======
===== Failed to connect to ESP8266 =====

Failing to power, connect the serial TX & RX pins, or ground the P2 pin can result in the following error message.

<code>
Connecting...

A fatal error occurred: Failed to connect to ESP8266
</code>

===== Program doesn't seem to be running =====

If your upload appears to be successful, and your code doesn't appear to be running, this is usually due to having not run OakRestore, and the Oak bootloader not knowing to run the program loaded in slot 0. Serial uploads always load to slot 0, but OTA updates load into slots 1 and 2, and the bootloader is probably trying to run programs from those slots, instead of your new serial uploaded program. Follow the [[https://github.com/digistump/OakRestore|steps to reset your Oak to factory defaults]], and all should be good.
Digistump Wiki

User Tools

Site Tools

Page Tools
