Overview

If a software update is published for one or more of the processors in the stack, the user can apply the update by following the instructions on this page. In addition, if the data on P3's SD card becomes corrupted, the card can be returned to factory condition by following the instructions as far as reprogramming P3.

The instructions below walk through reprogramming the stack in reverse order, i.e. P3, P2 then P1. Some updates will require only updating P3; others will require updating P3 then P2, in that order. Updates to P1, if they are required, should be applied last of all.

MIRO ships with firmware already installed—unless you have been advised to update it, you should not need to reprogram the stack.
Do not attempt to reprogram any part of the stack unless it is required—if reprogramming does not complete correctly, your MIRO robot will no longer function.
Reprogramming P3 means reflashing the SD card with a factory-supplied image—please remember that this will delete any user data on the card so this should be stored elsewhere during the update.

Update

Software updates will be delivered in the form of a new MDK release. The releases are tagged with a code YYMMDD, and each release will indicate which parts of the system need to be updated to move to the new release. Releases should not be mixed freely, but can be assumed to be backwards compatible with firmware that is not updated by that release.

First, obtain the updated MDK and install it on your workstation. See Prepare workstation.

Reprogram P3

You can use any micro-SD card of at least 4GB in size with MIRO; MIRO ships with a suitable card, but you might usefully maintain multiple cards with different configurations.

Choose options

Before we program the card, we need to choose an options string to pass to the programmer. Concatenate the options below, as required.

If your MIRO does not need special configuration, you may not need any of these options; however, be aware that not setting a root password may be a security risk.

Data partition size

By default, the data partition is 2GB. If you have a card larger than 4GB, you can choose a larger size by using the option string --data=<gigabytes> (where <gigabytes> can be between 2 and 28). The size of paritition that will fit will be 2-4GB smaller than the card itself—start at (size-2GB) and decrease the size until you don't get an error message.

Root password

Choose a root password, and use the option string --pass=<password>. If you do not select a root password, anyone will be able to log in to your MIRO as root and this may pose a significant security risk to your network.

Even if you do set a root password, which is recommended, you can still login without being prompted; you'll need sshpass installed and a command line of the form sshpass -p password ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@IP_ADDRESS.

Network credentials

The usual external interface to MIRO is the wireless network (WiFi) link. The network connection starts automatically when MIRO starts up, and you can then communicate with MIRO's on-board computer through SSH. In order for this to work, MIRO needs your network credentials.

You can program the card with your network credentials at this stage. Use the option string --network=<ssid>/<passphrase> (e.g. --network=my_ssid/my_passphrase).

You can alternatively supply network credentials in a file ~/.mdk/wpa_supplicant.conf on your workstation; if this file exists, its content will be appended to wpa_supplicant.conf during card creation. The two approaches to providing credentials are entirely equivalent, except that in a file you can specify as many networks as you like, whereas you can only specify one on the command line.

Network configuration

If you plan to run software, including the ROS master node, on-board MIRO, you can pass the option --onboard. If, instead, you want your robot to communicate with a ROS master on a remote machine, you need to provide the IP address of that remote machine, using --masteraddr=<address>. Both options modify the USER CONFIGURATION section at the top of the file at ~/.profile, so you can easily change these options on a programmed card.

If you do not specify either option, the default IP for the ROS master node is 192.168.1.100.

Swap

We prefer to run without swap, so that is the default. You can control this when you are programming the system using the option strings --swap=on and --swap=off (obviously, not both at the same time).

Program

To program the SD card, you will plug it into a card reader attached to your workstation. The card will appear with some physical device name under /dev, and you need to obtain this device name to proceed.

One way to obtain the device name is to open a terminal and enter ls /dev/sd* | grep -v [0-9] at the command prompt before and after plugging in your card reader; your card is the device name that appears.
Another way is to run dmesg | tail after plugging in the device—the last few lines will indicate the physical device name (something like "sdf", which would correspond to the device /dev/sdf).
The following procedure will erase the contents of a drive—you should ensure the correct drive (device name) is selected or the wrong drive may be erased.
The following procedure will erase the contents of your SD card—please ensure that no valuable files are on the card before beginning.
As with any such operation, you should be aware that files on any drive may be accidentally damaged or lost irretrievably owing to software errors—you should ensure that your workstation is backed up before proceeding.

Navigate to the bin folder in the MDK and proceed as follows to program the card. There is a safety check to reduce the chance of erasing the wrong device—the first time you program a card, you must start with it unplugged, and plug it in only when you are prompted to do so, or programming will not proceed.

You can put the options you chose, above, on the end of your command line, as shown below.

$ cd ~/mdk/bin/deb64 $ sudo ./program_P3.sh <device name> <your option string> ... check that file system <device name> is absent... OK! please plug in device, wait a moment, and then press a key... ...

By way of example, the programming line we use here is shown below. NB that your option line will very probably be different!

$ cd ~/mdk/bin/deb64 $ sudo ./program_P3.sh /dev/sdf --data=2 --pass=1234 --network=mironet/miropass --addr=192.168.1.101 --masteraddr=192.168.1.100 ...

On subsequent attempts to program the same card, the programming tool will recognise that the card has a MIRO system on it already and the safety check will be skipped (i.e. programming will proceed even if your card is already plugged in when you start the programmer). Please note that this will not protect any data you have stored on the card alongside the MIRO system—this will be erased if you reprogram the card.

Programming will now proceed, with some information along the way to let you know what's happening. If all goes well, the final step will be to unmount the card so that you can remove it from the card reader and plug it back into MIRO.

... (unmount)... (sync)... OK!

Reboot

After reprogramming the SD card, install it in MIRO and turn your MIRO on. MIRO will perform First Boot, which will slow down the boot process by just a few seconds, and will then be ready to use.

Update stored image

If you plan to commission multiple MIROs, you can—optionally—make changes to the P3 image files stored in a copy of the MDK and they will then be propagated to any MIROs you program from that copy.

You will find the system overlays stored at ~/mdk/image/P3/rootfs (mounted at /) and ~/mdk/image/P3/home (mounted at /home). You can safely add files as well as edit files, including making changes that you would usually make through the options passed to the programming tool, listed above. For instance, to add your network credentials at this level, edit the file at ~/mdk/image/P3/rootfs/etc/wpa_supplicant.conf. To add a user, add a home directory to ~/mdk/image/P3/home/<user> and add their details to configuration files in ~/mdk/image/P3/rootfs/etc.

Login through Debug Port

The image above shows the 3-wire Debug Port through which you can login to P3 as an alternative to logging in through the wireless network. This will not usually be necessary, but may prove helpful if access to the wireless is temporarily unavailable (access is always enabled).

Suitable USB adapters are such as CP2103, CP2104, FT232 (shown above), but any serial port will do; the port speed is 115200bps. A typical login session follows, where the user's adapter has been assigned /dev/ttyUSB0 by the workstation.

# screen -h 4000 /dev/ttyUSB0 115200 (...if screen is blank at this point, press RETURN) Poky (Yocto Project Reference Distro) 2.0.1 miro /dev/ttyO0 miro login: root root@miro:~#
Login to MIRO is as root—if you have set a root password, you will be asked for it.

Reprogram P2

The updated P3 system includes the firmware image for P2. If this is to be updated also, you should start by updating P3 (above), and then login to P3 as normal, proceeding as follows.

$ cd ~/mdk/bin/am335x $ ./program_P2.sh main programming ../../image/P2/P2_main.bin to sector 1... ________________________________________________________________ MIRO tools [miro_maint] Copyright (C) 2017 Consequential Robotics ________________________________________________________________ target: P2 mode: USB device: /dev/P2 operation: WRITE ________________________________________________________________ [000.000] enter/confirm maint mode... [000.000] MIRO_MAINT_OP_NOP... [NO RESPONSE] [000.271] MIRO_MAINT_OP_NOP... [NO RESPONSE] [001.281] MIRO_MAINT_OP_NOP... [OK] [001.534] MIRO_MAINT_OP_HANDSHAKE... [OK] ________________________________________________________________ [001.537] erase FLASH_WRITE_OK... [001.537] length: 4 (padded to block boundary at 256) [001.538] MIRO_MAINT_ERASE: 0xf0000... [OK] [001.978] MIRO_MAINT_WRITE.... [OK] ________________________________________________________________ [001.981] write main... [001.981] READ: "../../image/P2/P2_main.bin" [002.001] length: 160304 (padded to block boundary at 160512) [002.002] MIRO_MAINT_ERASE: 0x10000... [OK] [002.429] MIRO_MAINT_ERASE: 0x20000... [OK] [002.864] MIRO_MAINT_ERASE: 0x30000... [OK] [003.306] MIRO_MAINT_WRITE...................................... ................................................................ ................................................................ ................................................................ ................................................................ ................................................................ ................................................................ ................................................................ ................................................................ ................................................................ ................ [OK] ________________________________________________________________ [005.176] reinstate FLASH_WRITE_OK... [005.176] length: 4 (padded to block boundary at 256) [005.176] MIRO_MAINT_ERASE: 0xf0000... [OK] [005.610] MIRO_MAINT_WRITE.... [OK] ________________________________________________________________ [005.613] MIRO_MAINT_OP_RESET... [OK] ________________________________________________________________ **** SUCCESS ****
It is normal to see some warnings during startup of communications with the platform; therefore, seeing some warnings during programming does not necessarily indicate a problem.
If the ERASE phase succeeds but the WRITE phase fails mid-way, it may succeed if you try again.
If WRITE fails repeatedly and consistently, ensure the batteries are fully charged and try again.

Reprogram P1

Updates to P1 should not be required. In case they are, your workstation can connect to the UART programming port on the P1 board (UC4) using any available UART port. Remove the shell, and then proceed as follows.

  1. Connect a USB-to-UART bridge between your workstation and the debug port at UC4:J6, and tie BOOT0 to high. One way to do this is to use a 4-way cable as shown in the image with a CP2103 or similar bridge.
  2. Power-up MIRO by switching it on underneath. If the programming port is connected correctly, MIRO will not exhibit any behaviour (in particular, the display lights on either wheel arch will remain unlit). If they do light, P1 has not entered programming mode - check that the BOOT0 pin is being held high and cycle the power again.
  3. Open a terminal on your workstation and change into the bin directory of the MDK.
  4. Change into the sub-directory for your operating system.
  5. Run the programming tool, as shown below, using the supplied script.
$ cd ~/mdk/bin/deb64 $ ./program_P1.sh programming ../../image/P1/P1.bin... ________________________________________________________________ MIRO tools [miro_maint] Copyright (C) 2017 Consequential Robotics ________________________________________________________________ target: P1 mode: UART (57600bps) device: /dev/ttyUSB0 operation: WRITE ________________________________________________________________ [000.000] READ: "../../image/P1/P1.bin" [000.000] length: 65536 [000.000] HANDSHAKE... (ACK) [000.001] ERASE... (ACK) [000.001] MASS ERASE... (ACK) [000.025] WRITE................................................. ................................................................ ................................................................ ................................................................ .................. [OK] ________________________________________________________________ **** SUCCESS ****

If the programming script is not successful, check the connections between your UART port and UC4.

You may have to change the port specified in the supplied programming script program_P1.sh to suit your local system; edit the script as required.
To identify the port under Linux, run ls /dev/ttyUSB* both before and after you plug in the bridge.
To identify the port under Windows, look in Device Manager as you plug in the bridge.
P1 will only accept one program per reset, so always cycle MIRO's power before you try programming again.
If you get "Permission denied", you can either proceed using sudo or add your user to the dialout group and logout/login before trying again.