Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
toh:meraki:mr18:jtag [2020/04/12 16:44] – [Soldering] mhtoh:meraki:mr18:jtag [2021/09/06 23:21] – [Uploading a kernel] dddamion
Line 1: Line 1:
 ====== Meraki MR18 installation using JTAG and OpenOCD ====== ====== Meraki MR18 installation using JTAG and OpenOCD ======
  
-A modern firmware prevents installation of the Meraki MR18 using its own firmware, and therefore upgrading the device to OpenWRT requires use of the JTAG, which we're going to do using a Raspberry Pi and open source software. An overview of the process is:+A modern firmware prevents installation of the Meraki MR18 using its own firmware, and therefore upgrading the device to OpenWrt requires use of the JTAG, which we're going to do using a Raspberry Pi and open source software. An overview of the process is:
  
   * Disassemble the unit to access the UART   * Disassemble the unit to access the UART
   * Solder some pins to allow access to the JTAG   * Solder some pins to allow access to the JTAG
   * Connect both of these interfaces to a Raspberry Pi   * Connect both of these interfaces to a Raspberry Pi
-  * Upload an installation kernel into the device's memory using OpenOCD +  * Upload an installation kernel into the device's memory using [[http://openocd.org/|OpenOCD]] 
-  * Use the running kernel to carry out regular OpenWRT instructions to run the regular flashing process+  * Use the running kernel to carry out regular OpenWrt instructions to run the regular flashing process 
 + 
 +{{:media:meraki:mr18-reprogramming-using-raspberry-pi.jpg?200|}}
  
 ==== Disassembly ==== ==== Disassembly ====
Line 19: Line 21:
 Locate the JTAG port. The layout appears to be in line with a [[docs:techref:hardware:port.jtag|standard 14-pin EJTAG 2.6]]. Familiarise yourself with this port and which pins are which on the device you have in front of you. Locate the JTAG port. The layout appears to be in line with a [[docs:techref:hardware:port.jtag|standard 14-pin EJTAG 2.6]]. Familiarise yourself with this port and which pins are which on the device you have in front of you.
  
-At this point is recommended to remove the metal cover with the antennae attached. This is to allow access to the underside for soldering. To do this, unplug each of the antennae carefully, unscrew the two small screws (top-left and bottom-right) and slide the cover.+At this point is recommended to remove the metal cover on the mainboard which has the antennae attached. This is to allow access to the underside of the mainboard for soldering. To do this, unplug each of the antennae carefully, unscrew the two small screws (top-left and bottom-right) and slide the cover.
  
-For the purposes of this exercise, we only need a subset of the pins on one row: nTRST, TDI, TDO, TMS, TCK. We can also skip the 'ground' as the existing UART provides an equivalent ground pin.+For the purposes of this exercise, we only need a subset of the pins on one row: nTRST, TDI, TDO, TMS, TCK. We can also skip the 'ground' if we're willing to use the ground pin on the UART.
  
-Using only one row of pins is to our advantage. If we were to solder a connector vertically on both rows they will protrude with the case, preventing re-assembly or, worse, shorting on the case. Instead, we can solder 90 degree pins to only one row, which doesn't affect reassembly should we wish to return to the JTAG at a later date.+Using only one row of pins is to our advantage. If we were to solder a connector vertically on both rows they will protrude with the case, preventing re-assembly or, worse, shorting on the case. Instead, we can solder right-angled pins to only one row, which doesn't affect reassembly should we wish to return to the JTAG at a later date.
  
-With access to the underside of the board (from removing the metal cover) it's easy and clean to solder to the 5 pins needed; you may even want to solder all 7 on that row if you want to experiment later with the reset pins.+With access to the underside of the board (from removing the metal cover) it's easy and clean to solder to the 5 pins needed; you may even want to solder all 7 on that row if you want to experiment later with the reset pins. It's recommended to solder and position just one pin to hold everything in place, before doing the rest.
  
 +{{:media:meraki:mr18-soldering-jtag.jpg?200|}}
 +{{:media:meraki:mr18-jtag-pins-sideways.jpg?200|}}
 ==== Serial connection ==== ==== Serial connection ====
  
Line 40: Line 44:
 </code> </code>
  
-Now locate the UART on the MR18, which already has some pins soldered. In our illustration, pin 1 is to the right.+Now locate the UART on the MR18, which already has some pins soldered. In our illustration, pin 1 is to the right, and pin 4 to the left is supply voltage which will go unused. 
 + 
 +{{:media:meraki:mr18-uart.jpg?200|}}
  
 Connect these to the Raspberry Pi's own UART using jumper wire: Connect these to the Raspberry Pi's own UART using jumper wire:
Line 49: Line 55:
 | 10           | UART 3 | MR18 to Pi | | 10           | UART 3 | MR18 to Pi |
  
-Note that TX and RX are symmetrical; that is TX (transmit) connects to receive on the other device and vice-versa.+Note that TX and RX are symmetrical; that is TX (transmit) connects to RX (receiveon the other device and vice-versa.
  
-We can now view the console of the MR18. Run the following command on the Raspberry Pi:+We can now view the console of the MR18. Run the following command on the Raspberry Pi.
  
 <code> <code>
 $ sudo apt install picocom $ sudo apt install picocom
-$ sudo picocom --baud 115200 /dev/ttyAMA0+$ sudo picocom --baud 115200 /dev/ttyS0     # swap for /dev/ttyAMA0 for older Raspberry Pi
 </code> </code>
  
-and now power up the device, and you should see the boot logs.  Leave this running in a terminal; it survives reboots of the MR18 and gives a live display on what the device is doing, which you'll need later.+and now connect power to the deviceyou should see the boot logs.  Leave this running in a terminal; it survives reboots of the MR18 and gives a live display on what the device is doing, which you'll need later.
  
-If you have any problem here, check that TX and RX are round the correct way. Some of the existing MR18 guides reported TX and RX on the MR18 to be the other way around. This either means there are different revisions of the board or, more likely, confusion over connecting TX to RX and vice-versa.+If you have any problem here, check that TX and RX are round the correct way. Information on the [[toh:meraki:mr18|Meraki MR18 main page]] reports TX and RX on the MR18 to be the other way around. This either means there are different revisions of the board or, more likely, confusion over connecting TX to RX and vice-versa.
  
 ==== JTAG connection (OpenOCD) ==== ==== JTAG connection (OpenOCD) ====
  
-Identify pin 1 on the JTAG because it has the square (not circular) solder pad and is the left-most pin when looking at the board from the direction we opened it.+Identify pin 1 on the JTAG because it has the square (not circular) solder pad and is the left-most pin in this illustratation: 
 + 
 +{{:media:meraki:mr18-jtag.jpg?200|}}
  
 Connect the Raspberry Pi to the device's UART and JTAG by conecting these pins: Connect the Raspberry Pi to the device's UART and JTAG by conecting these pins:
Line 75: Line 83:
 | 26           | JTAG 1 | nTRST      | | 26           | JTAG 1 | nTRST      |
  
-The actual mapping is derived from the description in OpenOCD'interfaces/raspberrypi-native.cfg file (see the commands below). We're going to make a slight modification to the file to prepare it for use:+The actual mapping is derived from the description in OpenOCD'interface/raspberrypi-native.cfg file (see the commands below). We're going to make a slight modification to the file to prepare it for use:
  
 <code> <code>
 $ apt install openocd $ apt install openocd
 $ cd ~ $ cd ~
-$ cp /usr/share/openocd/scripts/interfaces/raspberrypi-native.cfg ./+$ cp /usr/share/openocd/scripts/interface/raspberrypi-native.cfg ./
 </code> </code>
  
Line 87: Line 95:
 <code> <code>
 bcm2835gpio_trst_num 7 bcm2835gpio_trst_num 7
 +</code>
 +
 +Note that the raspberrypi-native.cfg is written for the Raspberry Pi models 1 and zero. Modify the peripheral address and speed coefficients to match your Raspberry Pi model as follow:
 +
 +RPI 1A/A+/B/B+ with 700 MHz base clock
 +<code>
 +bcm2835gpio_peripheral_base 0x20000000
 +bcm2835gpio_speed_coeffs 113714 28
 +</code>
 +
 +RPI 2B with 900 MHz base clock
 +<code>
 +bcm2835gpio_peripheral_base 0x3E000000
 +bcm2835gpio_speed_coeffs 146203 36
 +</code>
 +
 +RPI 3B with 1200 MHz base clock
 +<code>
 +bcm2835gpio_peripheral_base 0x3E000000
 +bcm2835gpio_speed_coeffs 194938 48
 +</code>
 +
 +RPI 3B+ with 1400 MHz base clock (despite the higher clock seems to be the same as RPi 3B)
 +<code>
 +bcm2835gpio_peripheral_base 0x3E000000
 +bcm2835gpio_speed_coeffs 194938 48
 +</code>
 +
 +RPI 4 with 1500 MHz base clock
 +<code>
 +bcm2835gpio_peripheral_base 0xFE000000
 +bcm2835gpio_speed_coeffs 236181 60
 </code> </code>
  
Line 124: Line 164:
 </code> </code>
  
-You should see the boot sequence halt in your serial console. And you can connect in to OpenOCD and issue more commands, such as resume, which you'll see the effect of in the serial console.+You should see the boot sequence halt in your serial console. And you can connect in to OpenOCD and issue more commands, such as resume, which you'll see has the effect of the boot sequence continuing in the serial console:
  
 <code> <code>
Line 136: Line 176:
  
 Download the kernel from Download the kernel from
-[[https://github.com/riptidewave93/Openwrt-MR18/releases]].  Don't worry that this is not the latest OpenWRT release; it is used only to bootstrap the installation. Extract the files to the home directory on the Pi.+[[https://github.com/riptidewave93/Openwrt-MR18/releases]].  Don't worry that this is not the latest OpenWrt release; it is used only to bootstrap the installation. Extract the files to the home directory on the Pi.
  
 Our plan to upload this code into the RAM of the device, and then point the CPU at it to execute, much like a bootloader would. Our plan to upload this code into the RAM of the device, and then point the CPU at it to execute, much like a bootloader would.
  
-Firstly, we need to catch the boot process earlybefore any significant hardware is initialised.+Firstly, we need to catch the boot process early. This is important, as we need to boot our own kernel before any hardware peripherals in the device have begun to initialize, but late enough that the processor has been set up correctly by the existing Meraki bootloader. 
 + 
 +On some devices this time window is very small.  Too early or too late will result in openocd failing to communicate properly with the processor.\\ 
 +Reports show the place to interrupt the boot process is during ''part1'' of the Meraki bootloader ''Copying image to memory ... ...'' as shown below: 
 + 
 +[[https://forum.openwrt.org/t/meraki-mr18-installation-using-jtag-and-openocd/77900/15|{{https://forum.openwrt.org/uploads/default/optimized/3X/e/4/e482bb3d5ef79abfa94e003eb19e224f0aef064a_2_690x394.png}}]] 
 +Note: It appears to be impossible to get the correct timing if using POE.
  
 Provide power to the MR18 and at that exact moment, run OpenOCD: Provide power to the MR18 and at that exact moment, run OpenOCD:
Line 150: Line 196:
 We're looking to interrupt the device very early in its boot sequence. You should be able to 'catch' it during the second stage bootloader, and certainly before of the Cisco's Linux code has run. We're looking to interrupt the device very early in its boot sequence. You should be able to 'catch' it during the second stage bootloader, and certainly before of the Cisco's Linux code has run.
  
-Now execute the following commands, one by one, by hand on the OpenOCD command line:+Now execute the following commands, one by one, by hand on the OpenOCD command line which is started by connecting into the running OpenOCD process:
  
 <code> <code>
Line 157: Line 203:
 </code> </code>
  
-First, disable the hardware watchdog, which will re-set the device automatically if it thinks the Cisco operating system has crashed (as is the case when the device is halted):+First, disable the hardware watchdog, which normally is there to re-set the device automatically if it thinks the Cisco operating system has crashed (and it will detect this when the device is halted):
  
 <code> <code>
Line 163: Line 209:
 </code> </code>
  
-Now upload the code to the device. The distributed file begins with a 1Kb header, normally used by the bootloader.  Since we aren't the bootloader we'd like to strip this first 1Kb of the file. The easiest way is to upload it 1Kb earlier in the device's memory than the code we're going to use:+Now upload the code to the device. The distributed file begins with a 1Kb header, normally used by the bootloader.  Since we aren't the bootloader we'd like to strip this first 1Kb of the file. The easiest way is to upload it 1Kb earlier in the device's memory than the code we're going to use (0x8005FC00 = 0x80060000 - 1Kb):
  
 <code> <code>
-> load_image   openwrt-ar71xx-nand-mr18-initramfs-kernel.bin 0x8005FC00+> load_image openwrt-ar71xx-nand-mr18-initramfs-kernel.bin 0x8005FC00 
 +</code> 
 +It should return something along the lines of:  
 +''downloaded 6353004 bytes in 43.844112s (141.504 KiB/s)'' 
 +<code>
 > verify_image openwrt-ar71xx-nand-mr18-initramfs-kernel.bin 0x8005FC00 > verify_image openwrt-ar71xx-nand-mr18-initramfs-kernel.bin 0x8005FC00
 </code> </code>
 +Again you should be able to see something like this:
 +''verified 6353004 bytes in 1.027853s (6035.985 KiB/s)''
  
 Now reset some registers and execute the kernel: Now reset some registers and execute the kernel:
Line 180: Line 232:
 </code> </code>
  
-You should see, immediately on your serial console, the booting of the Linux kernel for OpenWRT.+You should see, immediately on your serial console, the booting of the Linux kernel for OpenWrt.
  
 === Troubleshooting === === Troubleshooting ===
  
-I found the process above can be someone unreliable, not working 100% of the time. If you don'get a Linux kernel boot, try the following:+I found the process above can be somewhat unreliable, not working 100% of the time. The result is that the serial console either shows nothing, or perhaps some garbled characters. Mainly this can be resolved by doing the final steps again soon after: 
 + 
 +<code> 
 +halt 
 +resume 0x80060000 
 +</code> 
 + 
 +If this still doesn'workhere are some other things you could try:
  
   * Make sure you're halting with OpenOCD straight after powering the MR18 on, not too late.   * Make sure you're halting with OpenOCD straight after powering the MR18 on, not too late.
   * Executing the commands in the telnet connection by hand (not scripted) seemed to help, and also gives a feel for what's happening.   * Executing the commands in the telnet connection by hand (not scripted) seemed to help, and also gives a feel for what's happening.
   * Don't forgot to reset the registers before "resume"   * Don't forgot to reset the registers before "resume"
-  * If you don't see the kernel boot straight away, you can try a second time immediately without having to start again. Try "halt; resume 0x80060000" again; often this works. 
  
-The issue is likely to be that we're not resetting some register or memory, so the results are non-deterministic. It would be good to automate more of this process to 100% reliability; likely we are missing some memory or register setting.+The issue is likely to be that we're not resetting some register or memory, so the results are non-deterministic. It would be good to automate more of this process to 100% reliability by understanding this. But, for now it may be okyou only need to boot like this once per device, so if you got it to work just once, then continue to the next step.
  
-Thankfully, you only need to boot like this once per device, so if you got it to work just once, then continue to the next step.+==== Flashing OpenWrt ====
  
-==== Installing OpenWRT permanantly ====+The device is now running OpenWrt, but a reboot will return to the original Cisco firmware. Now we're going to actually flash the device.
  
-The device is now running OpenWRT, but a reboot will return to the original Cisco firmware. Now we're going to actually flash the device. +On your PC, download the latest OpenWrt from the [[toh:meraki:mr18|Meraki MR18]] page.
- +
-On your PC, download the latest OpenWRT from the [[toh:meraki:mr18|Meraki MR18]] page.+
  
 Now, disconnect your PC from the internet and connect it to the ethernet of the device. The device acts as a DHCP server as if it were to provide internet access. Now, disconnect your PC from the internet and connect it to the ethernet of the device. The device acts as a DHCP server as if it were to provide internet access.
Line 209: Line 265:
   - "Flash new firmware image" using the file just downloaded.   - "Flash new firmware image" using the file just downloaded.
  
-Wait for the device to reboot of its own accord, and verify that OpenWRT boots, using the serial console.+Wait for the device to reboot of its own accord, and verify that OpenWrt boots, using the serial console.
  
 ==== Reassembly ==== ==== Reassembly ====
  
-You now have a working MR18 with OpenWRT installed! Now you can re-assemble the device. Don't forget to reconnect all of the antennae disconnected, including the lone one which is on the case.+You now have a working MR18 with OpenWrt installed! Now you can re-assemble the device. Don't forget to reconnect all of the antennae, including the smaller one which is on the side of the case.
  
 ==== Notes ==== ==== Notes ====
Line 221: Line 277:
 === Installation using "sysupgrade" === === Installation using "sysupgrade" ===
  
-This didn't appear to work, so falling back to the web interface is necessary. The output is:+For the sake of automation it would have been nice to do the installation on the command line. But this didn't appear to work, so falling back to the web interface is necessary. The output is:
  
 <code> <code>
Line 233: Line 289:
 </code> </code>
  
-By contrast, the web interface looks like:+By contrast, an installation via the web interface looks like:
  
 <code> <code>
Line 258: Line 314:
  
 However this sort of reset did not seem to be as 'hard' as removing the power, and was not able to boot the new kernel. Plus, OpenOCD code itself (not configuration) acts on a 1 second pause after the reboot, by which time the device is well into its second stage bootloader. However this sort of reset did not seem to be as 'hard' as removing the power, and was not able to boot the new kernel. Plus, OpenOCD code itself (not configuration) acts on a 1 second pause after the reboot, by which time the device is well into its second stage bootloader.
 +
 +Ideally, if the process were automated reliably then connecting to the UART would be unnecessary (though we would still need the ground pin).
  
  • Last modified: 2023/10/15 16:53
  • by mh