------------------------------------------------
SECTION #1: Requirements, Cautions, and Warnings
------------------------------------------------
Requirements:
--Microsoft Windows (for use with SAM-BA) (there is also a Linux version of SAM-BA, but we haven't tried it)
--Atmel/Microchip SAM-BA utility (download instructions below)
--TWO (2) micro USB cables
--Conduit power supply
--Conduit (blue box) or Conduit IP67 (see WARNING below)

Firmware Types:
- "A" model Conduits shipped with AEP firmware (i.e. MTCDT-LAT1-247A or MTCDTIP-LDC3-266A)
- "L" model Conduits shipped with mLinux firmware (i.e. MTCDT-247L or MTCDTIP-LEU1-270L)
- MTCDT and MTCDTIP models can have AEP or mLinux firmware installed regardless of the model's firmware indicator ("A" or "L"). In other words, the "A" model Conduit can have mLinux and the "L" model Conduit can have AEP.

* CAUTION: This package contains instructions that are technical in nature with an expectation that the end user is able to understand things of a technical nature in regard to the use of Microsoft Windows (file system organization, Device Manager), serial terminal software (such as Tera Term, ZOC, or Putty), and the boot process of the Conduit. If you are not comfortable with this, then let the MultiTech support staff know this and we will start the RMA process to have your device repaired.

* WARNING: If you intend to perform this procedure on the Conduit IP67 26xx/27xx series, then be aware that opening the chassis of those models voids the warranty. The Conduit IP67 220x/25xx series required the end user to open the chassis in order to install SIM cards and/or SD cards into the blue-box Conduit inside and it is okay to open those models. While the procedure described in this document is similar for the Conduit AP (MTCAP), the MTCAP is not end-user serviceable and does not use the same connectors for programming.

* NOTE: If you can't satisfy the requirements below OR you cannot obtain or install the SAM-BA developer utility OR you don't feel comfortable using the SAM-BA developer utility software, then let the MultiTech support staff know this and we will start the RMA process to have your device repaired.
--> https://support.multitech.com


----------------------------------------------------------------
SECTION #2: Firmware Folder Placement and Installation of SAM-BA
----------------------------------------------------------------
1. Unzip the firmware archive (if you are reading this file, then you likely already performed this step).

2. Move the unzipped firmware folder to the root of your Windows C: drive. Why? There is a TCL script file used by the SAM-BA utility in the ZIP archive that uses a specific path for all of the files (e.g C:\RomBOOT-Flash<AEP/mLinux><version>-SAM-BA\). You may modify the TCL script to match your preferred path if you are comfortable with that. The TCL script file is a text file that SAM-BA will use to program the binaries into the NAND flash.
-- For example, move the unzipped AEP 5.0.0 firmware folder "RomBOOT-FlashAEP500-SAM-BA" so that it is located at the root of the C: drive:
---> C:\RomBOOT-FlashAEP500-SAM-BA\
---> If you have trouble moving the folder, then see SECTION #6 (Troubleshooting).

3. Download the SAM-BA developer utility for Windows (all instructions in this document were written for the 2.16 software):
--> https://www.microchip.com/DevelopmentTools/ProductDetails/Atmel%20SAM-BA%20In-system%20Programmer
-- SAM-BA 2.16 is best for Windows XP/Vista/7
-- SAM-BA 2.18 is best for Windows 8/10

4. Install SAM-BA
--> After the software installation there is a USB driver installation notice that opens in a web browser. KEEP THAT WINDOW OPEN because you will need it for the first-time installation of the driver. For example, the notice is located below for the 2.16 installation:
----> file:///C:/Program%20Files%20(x86)/Atmel/sam-ba_2.16/doc/usb_notice.html


-------------------------------------------------------------
SECTION #3: USB Connections and Serial Terminal Configuration
-------------------------------------------------------------
1. Unplug all cables (Power, Ethernet, and USB) from the Conduit. Don't plug anything into the Conduit until instructed.

2. Open the Windows Device Manager

3. Connect a micro USB cable from the Windows PC to the "Debug" micro USB port on the front of the Conduit. On the blue-box Conduit, the debug micro USB port is behind the MULTITECH plate on the front of the blue-box Conduit. For the Conduit IP67 26xx/27xx, the debug micro USB port is the one closer to 6 LEDs while the micro USB device port is next to a reset button.

4. WAIT until Device Manager shows an "XR21V1410 USB UART" serial port installed before proceeding. Sometimes this can take several minutes.

5. Connect a second micro USB cable from the Windows PC to the "USB Device" port on the back of the blue-box Conduit. For the Conduit IP67 26xx/27xx, the micro USB device port is next to a reset button.
--> WARNING: Moving the debug cable from step 3 above to the USB Device port WILL NOT WORK. You need both micro USB cables.

6. Configure a serial terminal application (Tera Term, Putty, ZOC, etc.) with the following settings:
-- COM Port: Use the "XR21V1410 USB UART (COMx)" COM port (this is the Conduit's debug port, where "COMx" is the COM port number, i.e. COM38)
-- Speed: 115200
-- Data-Parity-Stop Bits: 8-N-1 (8 data bits, None for Parity, 1 stop bit)

7. Refer to the USB driver installation notice from the Atmel SAM-BA software (i.e.  file:///C:/Program%20Files%20(x86)/Atmel/sam-ba_2.16/doc/usb_notice.html ) which was installed in SECTION #2. Follow the instructions for making sure your device shows up as a USB device port. In the "Ports (COM & LPT)" section of Windows Device Manager, the port might be called "AT91 USB To Serial Converter" or it may be called "Bossa Program Port". Take note of the COM port number for the USB device port. The USB device port is the port that will be used to perform the firmware programming procedure in SAM-BA.
--> For example, on my Windows 7 system the USB device port is "Bossa Program Port (COM48)" and the USB debug port is "XR21V1410 USB UART (COM38)"


--------------------------------
SECTION #4: Erase the NAND Flash
--------------------------------
* WARNING: If you WERE able to download and install the SAM-BA developer utility successfully (see SECTION #2), then you may proceed with this section. If you were NOT successful in downloading or installing the SAM-BA software, then let the MultiTech support staff know this and we will start the RMA process to have your device repaired.
--> https://support.multitech.com

* INFO: The Conduit's boot process is the following:
  a. RomBOOT
  b. Bootstrap
  c. U-Boot
  d. mLinux kernel

* NOTE: If your Conduit can boot up successfully through at least U-Boot (see sample debug output in step 2 below), then the procedure in this section is necessary. If your Conduit only produces the "RomBOOT" message and then stops, then go to SECTION #5. If your Conduit doesn't output anything from the debug port, then double-check the serial terminal settings in SECTION #3 (use the correct COM port--the debug USB port will appear WITHOUT power applied). If still nothing outputs to the serial USB port, then try the following resoltion:
--> https://support.multitech.com/support/case.html?action=view&id=78593

If you tried the resolution and you still get nothing in the debug output, then contact MultiTech Product Support:
--> https://support.multitech.com


1. Follow the instructions in SECTION #3 if you haven't done so already. Make sure the serial terminal application window is open and connected via the USB debug port.

2. Attempt to stop the boot process at U-boot. To do this, apply power to the Conduit and immediately type/press the Return/Enter key multiple times quickly in the serial terminal window until the boot process stops and presents the U-Boot> prompt. If the boot process continues into the kernel, then unplug power and repeat this step. An example of the debug output is shown below:
vvvvv ---------- EXAMPLE ---------- vvvvv
RomBOOT


AT91Bootstrap 3.5.3-r4 (Tue Apr 16 02:07:12 CDT 2019)

NAND: ONFI flash detected
NAND: Manufacturer ID: 0x2c Chip ID: 0x32
NAND: Disable On-Die ECC
NAND: Initialize PMECC params, cap: 0x4, sector: 0x200
NAND: Image: Copy 0x80000 bytes from 0x40000 to 0x2ef00000
PMECC: sector bits = 0x2, bit 1 means corrupted sector, Now correcting...
Correct error bit @[#Byte 0x66,Bit# 0x2] 0x74 -> 0x70
NAND: Done to load image


U-Boot 2016.09.01r1 (Apr 16 2019 - 02:06:31 -0500)

CPU: AT91SAM9G25
Crystal frequency:       12 MHz
CPU clock        :      400 MHz
Master clock     :  133.333 MHz
       Watchdog enabled
I2C:   ready
DRAM:  256 MiB
WARNING: Caches not enabled
NAND:  256 MiB
MMC:   mci: 0
env_relocate_spec: crc1_ok=0 saved crc=0xffffffff calculated crc=0xf9137807 flags=255
env_relocate_spec: crc2_ok=0 saved crc=0xffffffff calculated crc=0xf9137807 flags=255
*** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
vendor-id:  Multi-Tech Systems
product-id: MTCDT-210A
device-id:  19078600
hw-version: MTCDT-0.0
mac-addr:   00:08:00:4a:18:ff
Net:   macb0
Hit any key to stop autoboot:  0
U-Boot>
U-Boot>
U-Boot>
U-Boot>
^^^^^ ---------- EXAMPLE ---------- ^^^^^


3. At the U-Boot prompt, enter the command "nand erase.chip" (without the quotes).
vvvvv ---------- EXAMPLE ---------- vvvvv
U-Boot> nand erase.chip

NAND erase.chip: device 0 whole chip
Erasing at 0xffe0000 -- 100% complete.
OK
U-Boot>
^^^^^ ---------- EXAMPLE ---------- ^^^^^

4. Reboot the Conduit from U-Boot using the command "reset" (without the quotes) and it should then come up with RomBOOT in the debug port and stop. Follow the instructions in SECTION #5 to install the firmware.
vvvvv ---------- EXAMPLE ---------- vvvvv
U-Boot> reset
resetting ...
RomBOOT
^^^^^ ---------- EXAMPLE ---------- ^^^^^


-------------------------------------------------
SECTION #5: Install Conduit Firmware Using SAM-BA
-------------------------------------------------
1. Follow the instructions in SECTION #3 if you haven't done so already

2. Make sure the Conduit only boots to RomBOOT before continuing (see SECTION #4)

3. At this point, you should have the debug USB cable plugged in, the device USB cable plugged in, and the power cable plugged into the Conduit (power applied) with the Conduit waiting at RomBOOT (as seen in the debug output in the serial terminal). If you don't see the RomBOOT message from the debug port, then go back to SECTION #3.

4. Make sure the firmware folder is installed at the root of the C: drive (i.e. the default TCL script expects the folder structure at C:\RomBOOT-Flash<AEP/mLinux><version>-SAM-BA\ with the binaries at C:\RomBOOT-Flash<AEP/mLinux><version>-SAM-BA\<AEP/mLinux>\). See SECTION #2 for details.
-- For example, the unzipped AEP 5.0.0 firmware folder "RomBOOT-FlashAEP500-SAM-BA" is located at the root of the C: drive:
---> C:\RomBOOT-FlashAEP500-SAM-BA\      (includes the "AEP" folder, Instructions.txt, and mtcdt-flash-full-AEP.tcl)
---> C:\RomBOOT-FlashAEP500-SAM-BA\AEP\  (includes the AEP firmware binaries for four (4) partitions)

5. Run the SAM-BA utility. SAM-BA will usually auto-populate the "connection" and "board" fields.

6. In the SAM-BA utility, select the USB device port (\USBserial\COMxx) and the board type "at91sam9g25-ek". See SECTION #2 for details of the COM port number for the USB device port.
--> For example, on my Windows 7 system "Select the connection" = "\USBserial\COM48" and "Select your board" = "at91sam9g25-ek".

7. Click the "Connect" button to connect to the Conduit. If a PMECC dialog comes up, click OK (SAM-BA 2.12 Patch7 and newer versions removes this dialog pop-up).

8. In the SAM-BA window, click "Script File -> Execute Script File" and select the "mtcdt-flash-full-<AEP/mLinux>.tcl" script from the firmware folder on the C: drive (i.e. C:\RomBOOT-FlashAEP500-SAM-BA\mtcdt-flash-full-AEP.tcl). Click the "Open" button to start the programming process. If you see an error message about failing to find files:
   * Ensure the TCL script variables are properly edited
   * Ensure the TCL script is using the correct firmware path
   * NOTE: SAM-BA scripts do not stop running if an error is encountered!

9. The SAM-BA script will run and finish with "=== DONE. ===". For example, the output at the bottom of the SAM-BA window will show:
-I- 	Writing: 0x20000 bytes at 0x68C0000 (buffer addr : 0x2001147C)
-I- 	0x20000 bytes written by applet
-I- 	Writing: 0x154EC bytes at 0x68E0000 (buffer addr : 0x2001147C)
-I- 	0x154EC bytes written by applet
-I- === DONE. === 

10. Close the SAM-BA application after programming has finished.

11. Power cycle the Conduit (unplug power and then re-plug power).

12. Monitor the debug port on the front of the Conduit to make sure the Conduit is booting properly. When it has finished booting, it should show the splash output for the type of firmware that was installed (AEP or mLinux) (and the STATUS LED should flash with a heartbeat rhythm). For example, for AEP firmware you would see something similar to the following after the boot process finished:
vvvvv ---------- EXAMPLE ---------- vvvvv
    / \      | ____|   |  _ \
   / _ \     |  _|     | |_) |
  / ___ \  _ | |___  _ |  __/_
 /_/   \_\(_)|_____|(_)|_|  (_)

MultiTech Systems Application Enablement Platform with mLinux GNU/Linux

mLinux 5.0.0 mtcdt /dev/ttyS0


Version: 5.0.0-AEP
Date: 2019-06-28T13:44:39
mtcdt login:
^^^^^ ---------- EXAMPLE ---------- ^^^^^


---------------------------
SECTION #6: Troubleshooting
---------------------------
* Invalid chip ID when using "COMxx" instead of "\USBserial\COMxx" as the "Select the Connection":
  - This error is usually because SAM-BA was unable to access the selected COM port.
  - Do you get this error on your first attempt to run SAM-BA or does nothing happen so you run it again (getting a open new instance dialog)?
  - Make sure you're selecting the "\USBserial\COMxx" for the "Select the Connection" and not just the "COMxx".
  - Do you have two USB cables connected to the Conduit, and do you see both COM ports in the Device Manager?

* PC can't read USB identifier for the USB Device connection:
  - With both the Debug port and USB Device connected to the PC, unplug the Conduit's power and then plug it back in.

* "unable to realloc 48 bytes" when trying to browse to or running the TCL script:
  - The unable to alloc error is a SAM-BA bug. A fix for this problem is copying the "RomBOOT-Flash-<AEP/mLinux><version>-SAM-BA" folder (with files and subfolders) into "Documents" and edit the mtcdt-flash-full-mlinux.tcl with a text editor and change the rootPath to the "Documents" folder. When editing mtcdt-flash-full-mlinux.tcl make sure that the rootPath ends with \\. Note replace back slashes in the path with double back slashes (change \ to \\).
  - Example rootPath line:
    set rootPath "C:\\Users\\myuser\\Documents\\RomBOOT-Flash-AEP500-SAM-BA\\"

::Document Version R2019-07-12::