BioMOBIUS SHIMMER Tutorial

TRIL Centre's BioMOBIUS Research Platform: An Open, Shareable Software and Hardware Platform

Audience
New users of BioMOBIUS who want to use the capabilities of Shimmer.

Purpose
This tutorial instructs the reader step by step on how to connect and use the SHIMMER hardware device with the BioMOBIUS software components. This tutorial should normally take less than 90 minutes to complete.

Pre-requisites
It is assumed the reader is familiar with the BioMOBIUS platform, has read the User Manual and has carried out the PatchnGUI tutorial. A functioning SHIMMER device is also required. No previous development experience is required. Version: 2.1

Introduction
The SHIMMER (Sensing Health with Intelligence, Modularity, Mobility
SHIMMER Tutorial

and Experimental Reusability) wireless sensor platform may be used in conjunction with the BioMOBIUS software environment to collect, process and store biomedical data sets. This tutorial describes a step by step approach to achieve this objective. It is assumed that the reader is familiar with the main components of the BioMOBIUS platform. If not, the reader is first encouraged to study the following documentation: BioMOBIUS User Manual included as part of the product documentation suite PatchnGUI Tutorial available from http://biomobius.trilcentre.org/ SHIMMER - http://docs.tinyos.net/index.php/SHIMMER. Figure 1 shows the components used in the complete BioMOBIUS development path. This tutorial specifically describes the creation of a patch using the EyesWeb Graphical Development Environment and the subsequent use of this patch by the GUI Designer to produce the final BioMOBIUS application.

Figure 1- BioMOBIUS development path

Note that the block development components are described in the BioMOBIUS Developer Guide and the reader is encouraged to familiarise themselves with this document.

Scope
The tutorial demonstrates the use of the BioMOBIUS components that are necessary to connect a standard SHIMMER device, accept data from the device and display it to the user. It is intended that this information will then aid the user to: 1. Incorporate SHIMMER devices in future prototyping efforts. 2. Add support for additional hardware devices to the BioMOBIUS platform.

SHIMMER Tutorial

The tutorial does not cover the architecture of the SHIMMER device or other aspects of the BioMOBIUS platform such as block development, GUI Tool specifics, etc.

Background
Two tools will be used to create the application: 1. The EyesWeb Graphical Development Environment (GDE) is used to produce the patch object. 2. The UI Designer tool is used to create a User Interface (UI) application which enables the user to interface and control the EyesWeb patch. A typical BioMOBIUS patch/application receives data from a hardware device, processes this data in a defined manner and outputs the data to an external device or to a user interface. This tutorial adheres to this general scenario. It accepts info from the SHIMMER sensor processes the accelerometer data and outputs the data to a graphical display. The end result is a standalone BioMOBIUS application which displays the SHIMMER accelerometer data in real time. The tutorial creates the application in a four step process: 1. 2. 3. 4. Connect to the SHIMMER sensor. Creation of the EyesWeb patch. Creation of the UI application and link to the patch. Running the application in the Runtime environment.

The EyesWeb patch and UI application developed in this tutorial are also provided as a reference point in the C:\biomobius_workspace\ShimmerTutorial Folder. For the GUI (.eywrad) to find the application patch (.eywx file) by default you should place the .eywx files in the C:\biomobius_workspace\patches Folder. (see the user manual for the explanation why) SHIMMER_Demo_Patch.eywx SHIMMER_Demo_App.eywrad

SHIMMER Tutorial

To derive the most benefit from this tutorial, the reader should attempt to create the patch and application from the beginning and only refer to the samples when necessary. In reading this tutorial, it is recommended that the user consult the BioMOBIUS Glossary for an explanation of any new terminology and in addition the user should refer to the GDE and UI User Guides for further information on these development tools. This tutorial complements other tutorials that are contained within the BioMOBIUS documentation suite and on the website: http://biomobius.trilcentre.org/. Finally, for troubleshooting Bluetooth connectivity issues: refer to http://support.microsoft.com/kb/883259 .

SHIMMER Tutorial

SHIMMER Basics
The SHIMMER platform consists of a base board, optional add on boards and a series of firmware versions to match the hardware configuration. This tutorial requires only the base board and the following firmware build: http://tinyos.cvs.sourceforge.net/tinyos/tinyos1.x/contrib/handhelds/apps/BioMOBIUS/AccelGyro/ This firmware is also available on the LiveDVD provided by Realtime Technologies LTD (http://shimmer-research.com/). The main components on the SHIMMER base board are: MSP430 RISC CPU 8 channels of 12 bit A/D the first 3 channels are hardwired to the accelerometer, the next 3 channels are routed to the expansion board device and the remaining 2 channels are allocated to the physical cradle connector on the SHIMMER. Class 2 Bluetooth radio 802.15.4 Radio 3-Axis FreescaleTM Accelerometer This tutorial will connect to the SHIMMER using Bluetooth and will use the first 3 A/D channels to acquire the XYZ accelerometer data. Although Bluetooth is used as the physical connection mechanism between the PC and the SHIMMER, the interface is logically implemented on the PC side as a virtual COM port. For additional information on the SHIMMER http://shimmer-research.com/ http://docs.tinyos.net/index.php/SHIMMER platform, refer to and

Step 1: Connect the SHIMMER to BioMOBIUS

This step describes how to establish communications between the SHIMMER and your PC. Before proceeding, ensure that the Bluetooth device and stack are installed and working correctly on your PC. The Bluetooth software and hardware may be part of the PCs standard build or it may be comprised of an external USB transceiver and third
SHIMMER Tutorial

party software stack. In either case confirm that the system can successfully discover Bluetooth devices. The following steps use the Microsoft Bluetooth stack; similar steps should also apply if you are using an alternative stack. Start the Bluetooth Devices configuration tool in the XP Control Panel.

Figure 2 - Bluetooth Devices configuration panel

Click on the Add button

Figure 3 - Bluetooth device wizard

SHIMMER Tutorial

Click on the check box as shown in Figure 3 and hit the Next button. The system will search for available devices and display those that are found. Detected SHIMMER devices are labeled as FireFly-XXXX. If your SHIMMER device is not listed, select the Search Again button as shown in

Figure 4.

Figure 4 - Bluetooth device wizard

If the SHIMMER device is still not found, check the 4 character hexadecimal label of your SHIMMER sensor, confirm that the device is powered up (red LED is activated) and validate the Bluetooth network is working by successfully detecting other devices e.g. mobile phone or laptop. Refer to the manufacturers documentation supplied with your Bluetooth hardware and software for further troubleshooting steps. Once the device is detected, select the device and click on the Next button as shown in Figure 5.

SHIMMER Tutorial

Figure 5 Click on device and click next

Select the Let me choose my own passkey radio button and enter the value 1234 as shown in Figure 6 and click on the Next button

Figure 6 - Enter passkey '1234'

SHIMMER Tutorial

The system will attempt to connect to the SHIMMER as shown in Figure 7 and a number of pop up windows will detail the progress.

Figure 7 - Installing the Bluetooth device

Eventually, Figure 8 will appear confirming that the Bluetooth device has been added successfully.

Figure 8 - Successful installation screen

Click on the Finish button to close down the device wizard.

SHIMMER Tutorial

Open up the Bluetooth configuration panel via the control panel. Click on the COM Ports tab and note the COM port assignment as shown in Figure 9. Hit OK to close the Bluetooth Devices configuration tool.

Figure 9 - COM port assignments

SHIMMER Tutorial

10

Step 2: Creating the SHIMMER Patch

Now that the SHIMMER is connected over Bluetooth, you will use the EyesWeb GDE to develop your patch. You will use blocks from the EyesWeb catalogs to implement your logic by drawing these objects on a palette and connecting the blocks to define the data flow. To aid clarity, the patch has been broken down into the following functional sections: 1. Controlling the SHIMMER how to start and stop streaming data from the SHIMMER 2. Acquiring the SHIMMER accelerometer data how to select the accelerometer data and display it 3. Reading the SHIMMER status how to read the SHIMMER status and display it

2.1 Controlling the SHIMMER

Objective: allow the user to connect and disconnect from the SHIMMER Open up the EyesWeb GDE from the start menu: Start->All Programs->BioMOBIOUSx.x->EyesWeb

SHIMMER Tutorial

11

Figure 10 - EyesWeb GDE

The application will start with a default clean palette named EywPatch1. If it fails to start as described, browse to the folder in which you installed BioMOBIUS, hold down the control and shift keys and double click on the EywGUI.exe application. The EyesWeb blocks are located in the catalog folder pane on the left hand side of the screen. Ensure that the catalog pane is as displayed in Figure 11 i.e. the display is using the catalog view. If this is not the case then click on the circled button to switch from the library view to the catalog view.

SHIMMER Tutorial

12

Figure 11- EyesWeb catalog view

Add the SHIMMER block. In the catalog view select the BioMOBIUSHardwareIO->BioMOBIUS->Hardware catalog library. Use the properties pane to configure the following parameters: Connect Start Stop Disconnect Clicking on the check boxes for these parameters enables four parameter pins on the block. Set the serial parameter to the COM port number that the Bluetooth stack assigned above e.g. 8. The outgoing COM port is the one used because it is the PC that initiates the

SHIMMER Tutorial

13

connection to the SHIMMER in this scenario, i.e. the PC is the Bluetooth master and the SHIMMER is the Bluetooth slave. The finalized property listing for the SHIMMER is shown in Figure 12.

Figure 12 - Properties of the SHIMMER

Connect the control buttons to the SHIMMER. Copy across the activation blocks onto the patch and connect these to the four parameter pins. This allows the user to control the operation of the SHIMMER block. We will also use two delay blocks in order to synchronise the connect and disconnect buttons with the start and stop transmission parameter pins. The control buttons are BangGenerator blocks located in the UI Objects catalog folder. Copy across the four blocks on to the palette, label and wire them as shown in Figure 13. The button descriptions are controlled by the Caption property. Set the Caption and Label properties accordingly e.g. for the Connect block set the Caption
SHIMMER Tutorial

14

and Label properties to Connect. When connecting the blocks to the SHIMMER block ensure that you match the button caption with the correct parameter pin hovering over the parameter pin with the cursor will display its name on the GDE status bar. Another tip to create the angled connection between button and parameter pin, first connect as normal by clicking the left mouse button on the output pin, then drag the cursor from the output pin and release the mouse button when you require to change direction. Click again on the left mouse button and drag the cursor in the new direction and continue on until you connect to the parameter pin.

SHIMMER Tutorial

15

Figure 13 - Diagram of how the blocks should be wired

Next we add in two delay blocks so as to auto start/end the transmission after the connect/disconnect buttons are activated. The delay blocks are located in the Kernel>FlowAndControlStructures catalog folder. Drag them across and wire them as shown in Figure 14 and set the delay parameter in each block to one second i.e. 00:000:01:000.

SHIMMER Tutorial

16

Figure 14 - Location of delay blocks

The final act in setting up the control buttons for the SHIMMER device is to connect the two delay blocks to the Disconnect and Start Transmission blocks so that they are automatically triggered when the Stop Transmission and Connect buttons are activated.

SHIMMER Tutorial

17

To do this, enable the BangGenerator parameter for the Disconnect and Start Transmission blocks and wire in the delay blocks as shown in Figure 15.

Figure 15 - Illustration of wired delay blocks

The rationale here is that the user is presented with only two controls to start and stop collecting data from the SHIMMER. Save your patch as MyShimmer.eywx in the C:\biomobius_workspace\Patches folder. You may now run the patch by clicking on the go button as shown in Figure 16. If the patches are saved in a different folder they cant be located by the EyesWeb Runtime Kernel which will produce an error in BioMOBIUS. This is important is you want to run a GUI later with your application.

SHIMMER Tutorial

18

Figure 16 - Position of 'GO' button in the EyesWeb GDE

Clicking on the Connect button will initiate the code on the SHIMMER and the green LED will light after approximately 5 seconds. The yellow LED will then start to flash indicating that the device is streaming data. The sample patch file C:\biomobius_workspace\ShimmerTutorial\Shimmer_Tutorial _Part1.ewyx illustrates the functionality added in this step.

2.2 Acquiring the SHIMMER data

Objective: to allow the user to read data from a specific SHIMMER data channel. Continue to use the MyShimmer.eywx patch developed in step 2.1 Add the InputSelector block from the Kernel>FlowAndControlStructures catalog library. Use the properties pane to specify 6 inputs. Connect the first six ADC outputs from the SHIMMER block to the six inputs on the InputSelector block as shown in Figure 17.

SHIMMER Tutorial

19

Figure 17 - Properties of the 'InputSelector' block

The user can select which channel is routed to the output pin of the InputSelector block by adding the following blocks to generate the channel number as shown in Figure 18:

SHIMMER Tutorial

20

Figure 18 - Add these blocks to generate the channel number

1. BangGenerator in the catalog GUI Objects. Set the caption to Initialise and the Patch Start setting to TRUE in the properties pane. 2. ConstantGenerator int in the catalog library Kernel->Math>Scalar. Set the SynchIn value to TRUE, this allows the BangGenerator block to fire the integer output which in turn is wired to the InputSelector parameter pin. Finally, set the Input Value setting to 0 as shown in Figure 19. This Input Value will be used later in the UI application so as to allow the user to select the ADC channel data.

SHIMMER Tutorial

21

Figure 19 - Set value to zero

Next wire the output of the InputSelector block to a buffering block so as to collect the discrete data values and buffer them into a matrix. This is required so that the data can be transmitted more efficiently to our UI application. (Note: We will develop this later in the tutorial) The buffering block is the FastDataBufferMatrixInput and this is located in the BioMOBIUSBase->BioMOBIUS->Base catalog library. Wire up this block to the output of the InputSelector block and set the Buffer setting to 500 as shown in Figure 20.

SHIMMER Tutorial

22

Figure 20 - Set buffer value to 500

This completes this section on acquiring the SHIMMER data save your patch again as MyShimmer.eywx. Run the patch and click on the Connect button, we do not see any visual representation of the streaming data, rather the data is available on the output pin of the FastDataBufferMatrixInput block. We will access this data and display it in our UI application later on in this tutorial. The patch file C:\biomobius_workspace\ShimmerTutorial\Shimmer_Tutorial _Part2.ewyx illustrates the functionality added in this step. To confirm that you are acquiring data from the SHIMMER at this stage, you can add the MatrixDisplay block from the System->Math>Matrix->Output catalog library. Set the Docked and FullScreen settings to false as shown in Figure 21. Run the patch, click on the Connect button and the channel data will be displayed. You can manually switch channels by entering a different value for the Input Value setting in the properties pane of the ConstantGenerator int block.

SHIMMER Tutorial

23

Figure 21 - Confirming the output of data from the SHIMMER

2.3 Reading the SHIMMER status

Objective: to read the SHIMMER status and display it. The SHIMMER status is available as an integer value on the Status output pin of the SHIMMER block. The integer value is used to select a corresponding predefined string to display the status to the user in the UI application. Continue to use the patch developed in the previous steps. Add a ConstantGenerator int block from the catalog library Kernel->Math->Scalar. Enable the Input Value parameter setting as shown in Figure 22 and set its value to 0. Connect the Status output pin of the SHIMMER block to this blocks input pin.

SHIMMER Tutorial

24

Figure 22 - Connect block to 'Status' pin as shown

Now add the TextSelect block from the BioMOBIUSBase>BioMOBIUS->Base catalog library. Set the Caption property to StatusText. Set the String0 to String3 parameter settings as follows: String0 String1 String2 String3 Not Connected Connected Transmitting Low Battery

Add a StringDisplay block from System->String->Output catalog library so as to the display the SHIMMER status on the patch. Again, this is not necessary for the UI application. The UI application will link directly to the output pin of the TextSelect block. We include it here for demonstration purposes. Connect up these blocks as shown in Figure 23.

SHIMMER Tutorial

25

Figure 23 - Connect 'TextSelect' block as shown

The patch is now complete, save it to the C:\biomobius_workspace\Patches folder and run it. The status of the SHIMMER will change as you connect and disconnect. If required, you can examine the sample patch C:\biomobius_workspace\ShimmerTutorial\Shimmer_Tutorial _Part3.ewyx which illustrates the patch creation steps up to this point. The next phase in this tutorial is to develop a UI application that will extract the data from your newly created patch and display it using rich graphical components to the user.

Step 3: Creating the GUI application

Now that your patch is controlling the SHIMMER and successfully receiving data, you will use the BioMOBIUS UI Designer tool to develop an application which will abstract the patch functionality and provide
SHIMMER Tutorial

26

the user with a rich user interface. Open the BioMOBIUS UI Designer from the start menu. Start a new blank UI from the File menu. Import the MyShimmer.eywx patch that you have just created by selecting File and Import Eyw patch. Navigate to the C:\biomobius_workspace\Patches folder where you saved the patch and open it. The UI under development is now linked to this patch and controls can be connected to the input and output pins of the blocks in the MyShimmer.eywx patch.

Figure 24 GUI linked to the MyShimmer.eywx patch

The UI designer contains a list of control and output components in the left hand pane. We will draw these on the palette pane to create our application. Note that the mechanism for creating a control in the UI is to select and draw rather than the drag and drop mechanism used in the EyesWeb GDE.

The first step is to create and link controls that will allow the user to specify the COM port number and connect/disconnect from the SHIMMER. Select and a draw a Text Control and a Text Draw component

SHIMMER Tutorial

27

onto the palette as show in Figure 25.

Figure 25 Add a Text Control and Text Draw component

Change the Text Draw text to COM Port: Click on the Text Control to highlight it and then click on the EyesWeb->parameter box in the properties pane. A dialog box pops up listing the inputs, outputs and parameters in our EyesWeb patch. This is depicted in Figure 26. Select the SHIMMER_1->Serial Port parameter and hit OK. This ties the value of the text box in the UI to the serial port parameter value in the SHIMMER block.

Note: an unconnected control will appear on the palette with a red X drawn through it to indicate its undetected state and the EyesWeb>parameter box in the properties pane will read Not Linked.

SHIMMER Tutorial

28

Figure 24 Tying Text Control to the patch parameter

Next, select and draw a Button control, name it Connect and tie it to the Connect->BangGenerator trigger of the EyesWeb patch as shown in Figure 27.

SHIMMER Tutorial

29

Figure 25 Tying Button Control to the patch

Follow the same steps to create the Disconnect button control and link it to the Disconnect->BangGenerator trigger of the EyesWeb patch. Complete this section by adding a Static Text control. Set the text to SHIMMER Control and enclose all the components with a rectangle as shown as shown in Figure 28. Note that it is convenient at this point to change the Z-order of the rectangle component to send it to the back of the palette select the rectangle and change the Z-order in the right hand properties pane.

SHIMMER Tutorial

30

Figure 26 Completing the SHIMMER Control section

Now it is time to display the SHIMMER data. The control that is required is the Oscilloscope Output. Select this control and draw on the palette as shown in Figure 29. Link this to the EyesWeb output FastDataBuffermatrix_1->Matrix. Set the max vert axis value to 4096, this corresponds to the 12 bit value out of the SHIMMER ADC channel.

SHIMMER Tutorial

31

Figure 27 Adding the oscilloscope output component

The final control that is required is to display the SHIMMER status. Select and draw a Text Static item, followed by a Text Output and link this to StatusText->OutputString. Now add a static text label and enclose it in a rectangle as shown in Figure 30.

SHIMMER Tutorial

32

Figure 30 Adding SHIMMER status components

Finally and for completeness, change the palette caption to SHIMMER Tutorial as shown in Figure 31.

SHIMMER Tutorial

33

Figure 31 Completed application with palette tile set to SHIMMER Tutorial.

Save your application using the File->Save menu option. A dialog box appears, specify the name as MyShimmer and the location as C:\biomobius_workspace\GUI.

To test the UI:

SHIMMER Tutorial

34

1. Ensure the Kernel Runtime Server is started the UI app connects to the EyesWeb patch through the Kernel Runtime Server. To start the server, click on Start>Programs->BioMOBIUSx.x->Start Kernel Runtime Server. 2. Start the BioMOBIUS UI Runtime from the Designer menu: - click on the Tools menu item and select Run. The runtime UI appears on screen - if this fails to start correctly then please refer to FAQ Support section on biomobius.trilcentre.org. 3. Press the start patch execution button on the UI (highlighted in Figure 32) or press Ctrl+S and the patch timer should start. The COM port and status components will display the correct values if the application and patch are communicating correctly.

Figure 32 Start executing the patch

If this is not the case then refer to the GUI Designer User Guide for further information. 4. Click on the CONNECT button the status should change to Connected after approximately 10 seconds. Confirm that the green LED on the SHIMMER device turns on/off as you connect/disconnect. Congratulations, you have BioMOBIUS UI application. successfully created your

SHIMMER Tutorial

35

Step 4: Run the UI application in the runtime environment

The Kernel Runtime Server enables the execution of your patch outside of the EyesWeb GDE. In other words, the end user of your application need not have any knowledge of the EyesWeb GDE. Similarly, the BioMOBIUS UI Runtime enables the execution of your UI application outside of the UI Designer tool. Using these runtime components is the standard method of executing the application after it has been developed and tested as described in the previous three steps. To run your application with the runtime components: 1. Ensure the EyesWeb GDE and UI Designer tools are terminated. 2. Ensure the Kernel Runtime Server is running. There is a link provided Start->Programs->BioMOBIUSX.X->Start Kernel Runtime Service. 3. Create a batch file with the following command:
installdir\BioMOBIUS_GUI_Runtime.exe" C:\biomobius_workspace\GUI\MyShimmer.eywrad

where installdir is the folder in which BioMOBIUS is installed e.g. c:\Program Files\BioMOBIUSx.x Execute this batch file and your application will run independently of the UI Developer tool as shown in Figure 33.

SHIMMER Tutorial

36

Figure33 - Executing the application in the runtime environment

Next Steps
Add additional functionality and components to the SHIMMER patch and GUI. For example, add a component to select the ADC channel, also persist the captured data to file as demonstrated in the demo version of the patch and GUI. Browse through the BioMOBIUS catalog blocks as described in the BioMOBIUS Blocks Reference Document in the product document folder Shortcut provided Start->Programs->BioMOBIUSX.X->BioMOBIUS Blocks Documentation. The user is also encouraged to mail any feedback, suggestions and support requests to biomobius.support@trilcentre.org.

SHIMMER Tutorial

37