Overview

This page provides instructions on how to reconfigure the MIRO platform.

The operations described on this page are a superset of those used by MIROapp to configure the platform and bridge through the Bluetooth link; observing the changes made to the files listed here will illustrate how MIROapp configures your MIRO.

Configure the platform through the bridge

The bridge, miro_bridge, accepts a broad set of arguments to configure its own behaviour and/or that of the platform—run it without arguments to list them. You can test a new configuration by using these parameters at the command-line, and then make it sticky by modifying the script that is usually used to run the bridge, ~/bin/run_bridge_ros.sh. Once this is done, future instantiations of the bridge through MIROapp will use the new configuration.

The remainder of this section discusses each parameter in turn.

If you have already configured the bridge to start at boot, you can quickly bring it down using stop_bridge.sh from MIRO's prompt.
You can run miro_bridge without arguments at any time to see help for all the available options.

Robot name

MIRO's default name as exposed to the network is "rob01" (the default name for a simulated MIRO is "sim01"). That will cause MIRO to publish/subscribe ROS topics under /miro/rob01. If you are using only one MIRO in your environment, that will do fine. If you need to use more than one, you can set their names to anything you like (though "rob02", "rob03", etc., would be our suggestion).

The bridge accepts an argument robot=<robot_name> which sets this name. Typical syntax would be miro_bridge net=ros name=rob02, though of course you may prefer a name that makes sense to you.

Camera parameters

You can also change the camera parameters when the bridge is already running by sending the platform/config message downstream; however, having the bridge start with your preferred camera configuration may be simpler.

You can choose the camera frame size and delivery rate through the arguments frame_size and frame_rate. The range of sizes and rates available is illustrated in the following table—if not specified, the default used is 320x240 @ 4fps.

frame sizeslowtypicalfast
128x9610fps15fps25fps
192x14410fps15fps25fps
320x2404fps5fps8fps

MIRO will publish camera frames at the typical rate shown for each frame size with only very occasional dropped frames. The fast rate will offer a higher overall data rate at the cost of reduced reliability (some frames will be dropped), whilst the slow rate will offer improved reliability and reduced load on the receiver at the cost of a reduced data rate. You can choose any frame rate you like, these are just to give an idea of the range.

Typical syntax would be miro_bridge net=ros frame_size=192 frame_rate=15. You can add the additional argument show=f to see the actual frames being delivered, but you don't need that argument for normal operation. The actual frame rate selected will be the available rate closest to the specified target rate.

Sync rate

The default sync rate is every three cycles of the 50Hz base clock (i.e. at 50/3Hz), delivering three 50Hz packets at once, with a maximum latency therefore of two cycles (40 msec). You should not generally need to change this setting.

If your application requires that data be delivered in a more timely fashion, you can set a faster sync rate using the option sync_interval (set to 1 for zero latency delivery), but this may reduce the stability of other data streams (video, audio) depending on how they themselves are configured. We recommend that you do not select a value larger than three for the sync rate, though values up to six are available, mysteriously.

No publish

Usually, audio from MIRO's ear microphones is delivered through /miro/rob01/platform/mics, and camera frames through /miro/rob01/platform/caml and camr. If you are not using one or both of these signal streams, you can reduce the load on the bridge by passing one or both of the flags m (do not publish mics) and c (do not publish cameras) through the argument bridge (for example, use bridge=mc to turn off publishing of both).

You can disable publishing of these streams at the platform level—this may further reduce load on the bridge: use platform=mc, or some other combination.

Streaming audio

MIRO is equipped with a loudspeaker and can vocalise and/or, at your request, play your favourite music to entertain you while you solder and/or code. The bridge provides streaming audio functionality through loading sample files from the SD card. You can trigger their delivery down to the platform by sending the message bridge/stream to the bridge. If you need this functionality, the bridge will need to be able to find the sound files at startup.

An example sound library of public domain music clips is installed on your MIRO already at /home/root/sound. To have the bridge load this, the argument sound=/home/root/sound needs to be on the command line (it already is in ~/bin/start_bridge.sh). You will then be able to play these sounds through the GUI client. For details of how to create and install your own sound library to MIRO, see Bridge Interface.

You can see the individual sounds being loaded by passing log_level=verbose to the bridge.

Monitoring

To get some feedback on the traffic coming upstream through the bridge, you can use the show argument, which accepts a string of any number of characters (run miro_bridge without arguments to see what is available). For instance, pass show=v to get periodic readouts of the main battery voltage—the MIRO below will need its batteries changing soon...

$ miro_bridge net=ros show=v [000.000] loading interf ________________________________________________________________ MIRO tools [miro_bridge] Copyright (C) 2017 Consequential Robotics ________________________________________________________________ device: /dev/P2 network: ROS (/miro/rob01) sync_interval: (do not change) frame: (do not change) ________________________________________________________________ ... [001.635] VBAT: 4.62634 ...

The show argument can be useful while you are getting to know the bridge, but should not be used for normal operation.

Autostart

Once you have decided on your command line for the bridge, you can configure it to start when MIRO boots so that MIRO will be "ROS ready" right after being switched on. Whilst still logged in to MIRO, edit the file at ~/bin/user_ready.sh (vi and nano are available on-board), which runs once the boot process is complete. Uncomment the line that launches start_bridge.sh, as shown below, and the bridge will now start at boot, as configured in start_bridge.sh and run_bridge_ros.sh.

~/bin/user_ready.sh
################################################################ ## UPDATED BY bridge_control.sh - DO NOT EDIT THIS SECTION! # The line below is modified by bridge_control.sh when the user # asks to change the bridge autostart status in MIROapp. If the # line is to be changed manually, make sure only to add/remove # the comment mark so that this continues to work correctly. start_bridge.sh ## UPDATED BY bridge_control.sh - DO NOT EDIT THIS SECTION! ################################################################

Now reboot your MIRO. As the robot reboots, if you watch the LED indicators on the P3 board, you should see that the bridge is now starting automatically (LED2 will light when the bridge is running). Run rostopic list on your workstation to check that MIRO has exported the expected ROS topics.

If the topics are not listed as expected, or the LEDs do not light up as expected, log in to P3 again. Check if the bridge is up using ps aux | grep miro, and check the contents of /tmp/log/miro_bridge.* for clues as to what has gone wrong.

Serial number

In some circumstances, it may be useful to be able to uniquely identify a physical MIRO from a remote client. One way to do this is using the argument robot to miro_bridge, so that the ROS topic exposed carries the identity information. Alternatively, you can set the serial number of the robot and it can then be read back from the platform_state message content, field serial_number.

To do this, login to your MIRO and use the provided script set_platform_serial_number.sh, as follows.

root@miro:~> set_platform_serial_number.sh 42 ________________________________________________________________ MIRO tools [miro_maint] Copyright (C) 2017 Consequential Robotics ________________________________________________________________ target: P2 mode: USB device: /dev/P2 operation: WRITE ________________________________________________________________ ... [001.292] MIRO_MAINT_OP_NOP... [OK] [001.292] waiting for response... [OK] [001.546] MIRO_MAINT_OP_HANDSHAKE... [OK] ________________________________________________________________ [001.548] SERIAL NUMBER: "42" [001.548] length: 4 (padded to block boundary at 256) [001.548] MIRO_MAINT_ERASE: 0xe0000... [OK] [001.929] MIRO_MAINT_WRITE.... [OK] ________________________________________________________________ [001.932] MIRO_MAINT_OP_RESET... [OK] usb 2-1: USB disconnect, device number 3 ... root@miro:~> get_platform_info.sh ________________________________________________________________ MIRO tools [miro_maint] Copyright (C) 2017 Consequential Robotics ________________________________________________________________ target: P2 mode: USB device: /dev/P2 operation: INFO ________________________________________________________________ waiting for SYNC... [OK] P2_R_SYNC received, platform information follows: ________________________________________________________________ (processing stack versioning) P1: R170221 P2: R170221 P2b: U170202 P3: R170221 (stoats and weasels versioning) UC1: unversioned (0xF) UC2: v2 UC3: unversioned (0x0) UC10: v2 UC14: v2 UC15: v5 (platform configuration) serial_number: 0042 (platform status) VBAT: 4.8528V ________________________________________________________________

As can be seen, get_platform_info.sh now returns the serial number 0042.

We recommend that, if you set a serial number, you use the serial number provided with your MIRO, to avoid confusion.