Tutorials > ROS-IGTL-Bridge for Single-Board Computers
Introduction
The goal of this tutorial is to learn how to integrate a robotic system with medical image computing software using OpenIGTLink. Specifically, we will learn how to setup a Robot Operating System (ROS) and ROS-IGTL-Bridge on a single-board computer (SBC), and connect it to 3D Slicer running on a host computer. In this tutorial, we will use BeagleBone Black Wireless as an example of SBC, but any other SBC, such as Raspburry Pi could work in a similar manner.
Prerequisite
- Hardware
- A host computer for running 3D Slicer (macOS Sierra was used for testing)
- BeagleBone Black Wireless (BBB)
- microSD card 8GB or 16GB
- SD card reader for the host computer
- Softwre packages
- 3D Slicer - Version 4.10
- Ubuntu Linux for Beagle Board - Version 18.04
- Robot Operating System - Melodic Morenia
Create Ubuntu 18.04 bootable SD
We will create a SD card with Ubuntu 18.04. Although a BBB comes with pre-installed Debian Linux, no binary package of ROS is available for Debian Linux on BBB. You can still build ROS for BBB, it is not straightforward because of the limited onboard storage (eMMC). The SD will also expand the storage size and will make it easier to install additional packages.
Binary images of Ubuntu 18.04 is available at elinux.org. We will follow the instruction for “raw microSD image”:
Download the OS image and verify (for a Linux host):
$ wget https://rcn-ee.com/rootfs/2018-09-11/elinux/ubuntu-18.04.1-console-armhf-2018-09-11.tar.xz
$ sha256sum bone-ubuntu-18.04.1-console-armhf-2018-09-11-2gb* 39a4a24962e5241b7e0cb5b249f8dfddaa43b122d3826bcd923aa541321fb125 bone-ubuntu-18.04.1-console-armhf-2018-09-11-2gb.img.xz
If you use macOS, the image can be validated with ‘shasum’ instead of ‘sha256sum’:
$ shasum -a 256 bone-ubuntu-18.04.1-console-armhf-2018-09-11-2gb.img.xz 39a4a24962e5241b7e0cb5b249f8dfddaa43b122d3826bcd923aa541321fb125 bone-ubuntu-18.04.1-console-armhf-2018-09-11-2gb.img.xz
Before writing the SD image to the media, check the device name. On Linux, you can check available disks before and after connecting the SD card:
$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 465.8G 0 disk
├─sda1 8:1 0 195.3G 0 part
├─sda2 8:2 0 4G 0 part [SWAP]
└─sda3 8:3 0 266.5G 0 part /
sdb 8:16 0 465.8G 0 disk
└─sdb1 8:17 0 460.8G 0 part /home
sr0 11:0 1 1024M 0 rom
In Mac, run the following command after connecting the SD card:
$diskutil list
/dev/disk0 (internal):
#: TYPE NAME SIZE IDENTIFIER
0: GUID_partition_scheme 1.0 TB disk0
1: EFI EFI 314.6 MB disk0s1
2: Apple_CoreStorage Macintosh HD 999.6 GB disk0s2
3: Apple_Boot Recovery HD 650.0 MB disk0s3
/dev/disk1 (internal, virtual):
#: TYPE NAME SIZE IDENTIFIER
0: Apple_HFS Macintosh HD +999.2 GB disk1
Logical Volume on disk0s2
DFB2D908-FAE0-4DA1-9F8F-557F7F7B430D
Unlocked Encrypted
/dev/disk2 (external, physical):
#: TYPE NAME SIZE IDENTIFIER
0: FDisk_partition_scheme *15.9 GB disk2
1: Windows_FAT_32 NO NAME 15.9 GB disk2s1
In this case, /dev/disk2 is the SD card. On the Mac, you may need to unmount the disk before writing the disk image to the SD card:
$ diskutil unmountDisk /dev/disk2
Unmount of all volumes on disk2 was successful
Then write the SD card image with ‘dd’ command
$ xzcat bone-ubuntu-18.04.1-console-armhf-2018-09-11-2gb.img.xz | sudo dd of=/dev/disk2
3481600+0 records in
3481600+0 records out
1782579200 bytes transferred in 689.521240 secs (2585242 bytes/sec)
Boot from the SD card
In the following sections, we will work on the BBB from the host computer through the TCP/IP connection over the USB cable. You may need to install a driver for network-over-USB.
Insert the SD card to the slot on the BBB, and connect the BBB and the host computer using a USB cable. Once the booting process is completed, you will be able to login to the BBB from the terminal on the host computer:
$ ssh -X ubuntu@192.168.7.2
ubuntu@192.168.7.2's password:
Warning: untrusted X11 forwarding setup failed: xauth key data not generated
Last login: Tue Sep 11 20:20:52 2018 from 192.168.7.1
The default password is “temppwd”. Once you log into the system, make sure that the system has an internet connection. If you want to connect to a WiFi network, please follow How to setup WIFI from a Linux console.
Check the disk space on the system:
ubuntu@arm:~$ df
Filesystem 1K-blocks Used Available Use% Mounted on
udev 219152 0 219152 0% /dev
tmpfs 49580 3660 45920 8% /run
/dev/mmcblk0p1 1676616 1047448 525952 67% /
tmpfs 247880 0 247880 0% /dev/shm
tmpfs 5120 4 5116 1% /run/lock
tmpfs 247880 0 247880 0% /sys/fs/cgroup
tmpfs 49576 0 49576 0% /run/user/1000
The downloaded disk image is designed for a media size of 2GB, and the sytem already occupies 67% of the space. However, if you have a SD card larger than 2GB, you can re-allocate the partition by the following command:
ubuntu@arm:/opt/scripts/tools$ cd /opt/scripts/tools
ubuntu@arm:/opt/scripts/tools$ git pull
remote: Enumerating objects: 71, done.
remote: Counting objects: 100% (71/71), done.
remote: Compressing objects: 100% (27/27), done.
remote: Total 63 (delta 43), reused 56 (delta 36), pack-reused 0
Unpacking objects: 100% (63/63), done.
From https://github.com/RobertCNelson/boot-scripts
0aa8fd0..e9bcff2 master -> origin/master
Updating 0aa8fd0..e9bcff2
Fast-forward
boot/am335x_evm.sh | 32 ++++++++++++++++++++++----------
boot/beagle_x15.sh | 5 +++++
boot/omap3_beagle.sh | 5 +++++
network/doc-debian-setup.md | 11 +++++++++++
network/usb_linux_usb0_ics.sh | 14 ++++++++++++++
network/usb_linux_usb1_ics.sh | 14 ++++++++++++++
network/usb_mac_ics.sh | 15 +++++++++++++++
network/usb_windows_ics.sh | 15 +++++++++++++++
tools/update_kernel.sh | 41 +++++++++++++++++++----------------------
tools/version.sh | 11 +++++++++++
10 files changed, 131 insertions(+), 32 deletions(-)
create mode 100644 network/doc-debian-setup.md
create mode 100755 network/usb_linux_usb0_ics.sh
create mode 100755 network/usb_linux_usb1_ics.sh
create mode 100755 network/usb_mac_ics.sh
create mode 100755 network/usb_windows_ics.sh
ubuntu@arm:/opt/scripts/tools$ sudo ./grow_partition.sh
[sudo] password for ubuntu:
Media: [/dev/mmcblk0]
sfdisk: 2.26.x or greater
Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x6ae17082
Old situation:
Device Boot Start End Sectors Size Id Type
/dev/mmcblk0p1 * 8192 3481599 3473408 1.7G 83 Linux
>>> Created a new DOS disklabel with disk identifier 0xaec33366.
/dev/mmcblk0p1: Created a new partition 1 of type 'Linux' and of size 14.9 GiB.
Partition #1 contains a ext4 signature.
/dev/mmcblk0p2: Done.
New situation:
Disklabel type: dos
Disk identifier: 0xaec33366
Device Boot Start End Sectors Size Id Type
/dev/mmcblk0p1 * 8192 31116287 31108096 14.9G 83 Linux
The partition table has been altered.
Calling ioctl() to re-read partition table.
Re-reading the partition table failed.: Device or resource busy
The kernel still uses the old table. The new table will be used at the next reboot or after you run partprobe(8) or kpartx(8).
Syncing disks.
reboot
ubuntu@arm:/opt/scripts/tools$ sudo reboot
Connection to 192.168.7.2 closed by remote host.
Connection to 192.168.7.2 closed.
The last command ‘reboot’ will disconnect your SSH connection and reboot the BBB. Once it is rebooted, login with the same IP, username, and password.
$ ssh -X ubuntu@192.168.7.2
ubuntu@192.168.7.2's password:
Warning: untrusted X11 forwarding setup failed: xauth key data not generated
Last login: Tue Sep 11 20:20:52 2018 from 192.168.7.1
To confirm the disk size, run the ‘df’ command again:
ubuntu@arm:~$ df
Filesystem 1K-blocks Used Available Use% Mounted on
udev 219012 0 219012 0% /dev
tmpfs 49580 3636 45944 8% /run
/dev/mmcblk0p1 15289388 1057108 13580320 8% /
tmpfs 247880 0 247880 0% /dev/shm
tmpfs 5120 4 5116 1% /run/lock
tmpfs 247880 0 247880 0% /sys/fs/cgroup
tmpfs 49576 0 49576 0% /run/user/1000
Install ROS Melodic Morenia
The next step is to install ROS Melodic Morenia (the latest long term support (LTS) as of November 2018). Please follow the installtion instruction available at wiki.ros.org on the BBB’s console.
Install and test ROS-IGTL-Bridge
Once the ROS environment has been set up, follow the README file in the ROS-IGTL-Bridge package.