P11021: LVAD Software System - EDGEedge.rit.edu/content/P11021/public/design/software... · The...

Copyright © 2011 Rochester Institute of Technology

P11021: LVAD Software System

SDP/SDD

Software Development Plan/Software Design Document

Version 1.1

2011-03-22

Rochester Institute of Technology MSD

Rochester Institute of Technology MSD P11021: LVAD Software System - SDP/SDD

2011-03-22: A. Hoag Page ii

Revisions

Version Primary Author(s)

Description of Version Date Completed

0.1 (Draft) Andrew Hoag Initial revision. 2010-10-19

1.0 Andrew Hoag Release – Week 9 Detailed Design Review 2010-11-03

1.1 Andrew Hoag Release - Technical


2011-03-22: A. Hoag Page iii

Review & Approval

Software Plan Review History

Reviewer Version Reviewed

Signature Date

Andrew Hoag 1.1

Zachary Shivers 1.1

Smiha Sayal 1.1

Prof. Ed Hanzlik 1.1

Dr. Steven Day 1.1

Dr. ShanBao Cheng 1.1


2011-03-22: A. Hoag Page iv

Contents

REVIEW & APPROVAL ................................................................................................. III

1 INTRODUCTION ...........................................................................................................6

1.1 OVERVIEW ................................................................................................................6 1.2 ASSUMPTIONS AND CONSTRAINTS ............................................................................6 1.3 NOMENCLATURE .......................................................................................................6

2 SOFTWARE PROJECT MANAGEMENT .........................................................................7

2.1 RESOURCE IDENTIFICATION ......................................................................................7 2.1.1 Staff ............................................................................................................................. 7

2.2 TRACKING AND CONTROL .........................................................................................7 2.3 ENGINEERING ............................................................................................................7

2.3.1 Methods, Tools, and Techniques ................................................................................ 7 2.4 PROJECT ARTIFACTS .................................................................................................7

3 SOFTWARE QUALITY ..................................................................................................8

3.1 CODING STYLE AND STANDARDS ..............................................................................8 3.1.1 ANSI C ........................................................................................................................ 8 3.1.2 Spacing and Formatting ............................................................................................. 8 3.1.3 Function and Variable Naming .................................................................................. 8 3.1.4 File Header................................................................................................................. 8 3.1.5 Comments ................................................................................................................... 8 3.1.6 Type Definitions ......................................................................................................... 8 3.1.7 Preprocessor Directives ............................................................................................. 9 3.1.8 Header Files ............................................................................................................... 9 3.1.9 Function Return Values .............................................................................................. 9

3.2 TESTING ....................................................................................................................9 3.2.1 Unit Testing/White Box Testing .................................................................................. 9 3.2.2 Software Integration Testing ...................................................................................... 9 3.2.3 Hardware Integration Testing .................................................................................... 9

4 SUPPORTING PLANS ..................................................................................................10

4.1 CONFIGURATION MANAGEMENT .............................................................................10 4.1.1 Revision Control ....................................................................................................... 10 4.1.2 Release Process ........................................................................................................ 10

4.2 MAINTENANCE ........................................................................................................10

5 DETAILED DESIGN ....................................................................................................11

5.1 SYSTEM BACKGROUND ...........................................................................................11 5.1.1 HESA Data Acquisition ............................................................................................ 11


2011-03-22: A. Hoag Page v

5.1.2 Analog to Digital Sampling ...................................................................................... 12 5.1.3 PWM (Pump Motor and AMB Control) ................................................................... 12 5.1.4 Control Law - PID (Proportional Integral Derivative)............................................ 12

5.2 SOFTWARE REQUIREMENTS ....................................................................................12 5.3 MSP430F5438A NOTES .........................................................................................13

5.3.1 ADC .......................................................................................................................... 13 5.3.2 Timers and Interrupts ............................................................................................... 13 5.3.3 TI Provided Code ..................................................................................................... 13

5.4 SOFTWARE DESIGN .................................................................................................13 5.4.1 Software Subsystem Identification ............................................................................ 13 5.4.2 System States and Modes .......................................................................................... 17

Initializing ................................................................................................................................ 17 Operational ............................................................................................................................... 17 Maintenance ............................................................................................................................. 17 Degraded .................................................................................................................................. 18 Faulted ..................................................................................................................................... 18

5.4.3 Clocks and Timers .................................................................................................... 18 5.4.4 Overview of System Activity ..................................................................................... 19

6 DOCUMENTATION STANDARDS ................................................................................20

7 REFERENCES .............................................................................................................21


2011-03-22: A. Hoag

1 Introduction

1.1 Overview

This project plan is the top level controlling document for the P11021: LVAD Software Sys-

tem. As part of P11021’s control system miniaturization, a programmable microcontroller

will be used – this created the need for a software subsystem and corresponding documenta-

tion.

1.2 Assumptions and Constraints

The software schedule, resources, and milestones are ultimately defined and driven by both

the MSD schedule and P11021 schedule.

1.3 Nomenclature

ACLK Auxiliary Clock

ADC Analog-to-Digital Converter

AMB Active Magnetic Bearings

HESA Hall Effect Sensor Array

ISR Interrupt Service Routine

LVAD Left Ventricular Assist Device

MCLK Master Clock

PID Proportional Integral Derivative

PHX-35 Phoenix-35 Motor Controller

PWM Pulse-width Modulation

SMCLK Sub-Master Clock


2011-03-22: A. Hoag

2 Software Project Management

2.1 Resource Identification

2.1.1 Staff

Name Role Availability

Andrew Hoag Computer Engineer Sep 2010 - Feb 2011

Zach Shivers Electrical/Integration Engineer Sep 2010 - Feb 2011

Smiha Sayal P11021 Project Manager Sep 2010 - Feb 2011

2.2 Tracking and Control

Given the small size of the project time and team, tracking and control documents will be

contained within the project file structure. All software development changes shall be

tracked within a Microsoft Excel document describing the change and link to the correspond-

ing scheduled task. All defects shall also be incorporated into this document including re-

ported date, reporter, and resolutions.

2.3 Engineering

2.3.1 Methods, Tools, and Techniques

UML diagrams shall be used to show relationships. Flow charts may also be employed to

illustrate control logic.

2.4 Project Artifacts

All software project artifacts including design and documentation shall be archived and pro-

duced to the customer upon completion of P11021.


2011-03-22: A. Hoag

3 Software Quality

3.1 Coding Style and Standards

Application of code styling and standards benefits code readability, portability, and mainte-

nance while reducing the probability of programming errors and defects.

3.1.1 ANSI C

ANSI C (C90) shall be used in all software development to ensure compatibility with a wide

range of compilers and hardware architectures.

3.1.2 Spacing and Formatting

An indent shall consist of 3 spaces; the use of tabs must be avoided whenever possible. The

maximum line width shall not exceed 80 characters for ease of printing and viewing. Code

spacing shall follow the K&R style.

3.1.3 Function and Variable Naming

Function and variable names shall be descriptive, concise and refrain from beginning with a

capital letter.

3.1.4 File Header

Each source file shall include the following file header:

/******************************************************************************

* [Filename]

* Revision: $Id$

*

* Copyright 2011 Rochester Institute of Technology.

* All rights reserved.

*

* RIT MSD P11021

*

*****************************************************************************/

Where [Filename] is replaced with the file name, and $Id$ is the revision tag automatically

populated by the SVN revision control system.

3.1.5 Comments

All code shall be commented thoroughly using block comments (/* comment */) before func-

tion definition and C++ style comments (// comment) for inline comments.

3.1.6 Type Definitions

To ensure portability and compatibility across many hardware architectures, type definitions

shall be mapped for each hardware instance using a schema similar to Table 3.1.


2011-03-22: A. Hoag

Table 3.1: Example Typedef Map

Type Description Base 10 Range

char_t Signed 8-bit integer, char -128 to 127

uchar_t Unsigned 8-bit integer, unsigned char 0 to 255

int16_t Signed 16-bit integer -32768 to 32767

uint16_t Unsigned 16-bit integer 0 to 65535

3.1.7 Preprocessor Directives

#define directives (and related #ifdef, #ifndef, …) shall only be used as include guards, to

define constants, and to map hardware specific names (ex: pin names). These defines should

be used sparsely and have unique identifiers as they are within the global namespace.

#pragma directives shall only be used in hardware-specific mapping files for functionality

such as interrupt handling.

3.1.8 Header Files

All function prototypes shall be forwardly declared within a header file. Header files should

refrain from containing any core logic.

3.1.9 Function Return Values

All functions shall return Boolean values. Functions that produce other results shall modify

variables passed by reference.

3.2 Testing

3.2.1 Unit Testing/White Box Testing

Each function shall be associated with a thorough unit test. Stubs and mocks should be

avoided in unit tests. Gtest shall be used to perform these tests.

3.2.2 Software Integration Testing

One or more integration tests shall be created and utilized to test the interaction of functions

within the software system. Integration testing is unlike unit testing, and specific functions –

hardware operations – may be stubbed or mocked in an effort to provide valid stimuli. Gtest

shall be used to perform these tests.

3.2.3 Hardware Integration Testing

Integration tests shall be performed with the hardware. This will include testing HESA ac-

quisition, AMB control, and motor speed using the LVAD test fixture.


2011-03-22: A. Hoag

4 Supporting Plans

4.1 Configuration Management

All code, supporting documents, and results should be maintained within the Subversion revi-

sion control system on EDGE. A release configuration should easily be re-creatable for fu-

ture reference. Backup archives shall be created weekly.

4.1.1 Revision Control

Commits to the software baseline shall only be made by the Computer/Electrical team.

Comments provided during a commit should reference the ID number of associated tracking

and control entries.

4.1.2 Release Process

Prior to a software release, the following documents and artifacts must be reviewed and ap-

proved:

SDP/SDD (this document)

Tracking and Control Document

Software test results (Unit and software integration)

Hardware integration test results

These documents shall be sent to the team and necessary parties via e-mail for approval.

Each release shall contain:

Compiled binary – to be loaded on to device

README.txt – specific instructions for installing release on device.

CHANGELOG.txt – concise log of changes between releases, as documented in the

Tracking and Control Document

Copies of source code and artifacts.

4.2 Maintenance

The project P11021 has not yet identified specific requirements and processes related to

maintenance. However, the use of this document and quality processes aim to provide a

highly maintainable project.


2011-03-22: A. Hoag

5 Detailed Design

5.1 System Background

5.1.1 HESA Data Acquisition

The LVAD impeller levitation is monitored using hall-effect sensors. These sensors are in-

corporated into an assembly known as a HESA – Hall Effect Sensor Array. HESAs are

mounted in the front and rear sections of the pump. This is illustrated in Figure 5.1.

Figure 5.1: LVAD prototype exploded view (1)

Each HESA has 2 sensors, each with 2 outputs for a total of 8 analog signals. These signals

are annotated in Table 5.1. The difference between the positive and negative signals shall be

calculated in software producing X and Y values for the front and rear.

Table 5.1: HESA Signals

HESA Description

Front-x HFXP HESA front-x positive

HFXN HESA front-x negative

Front-y HFYP HESA front-y positive

HFYN HESA front-y negative

Rear-x HRXP HESA rear-x positive

HRXN HESA rear-x negative

Rear-y HRYP HESA rear-y positive

HRYN HESA rear-y negative


2011-03-22: A. Hoag

5.1.2 Analog to Digital Sampling

Each of the HESA analog channels is sampled at 5 kilo-samples/second (or every 200µs).

The software shall make use of the ADC timers and interrupts provided by the microcontrol-

ler architecture to control the sampling.

5.1.3 PWM (Pump Motor and AMB Control)

Pulse-width Modulation is a digital signal that is used to simulate an analog output by varying

high and low signals at intervals proportional to the value.

The AMBs are controlled using 4 PWM signals.

The pump motor is controlled using a single PWM output to the PHX-35 motor controller.

This PWM signal is in the standard R/C format (1), which is a 50Hz signal where motor con-

trol occurs between 1ms and 2ms with 1.5ms being the center value.

5.1.4 Control Law - PID (Proportional Integral Derivative)

PID is a common feedback control loop that is currently used in the LVAD control system.

The output signal is a function of the error, the error’s history, and the error’s rate of change.

Figure 5.2: PID Block Diagram (2)

5.2 Software Requirements

The software shall generate PWM signals for the AMBs at 20kHz, and the 3-phase

motor controller at 50Hz.

The software shall sample HESA values at 5kHz, input to the control loop, and up-

date the AMB PWM outputs.

The software shall report battery level, faults, and status to the user.

The software shall respond to user input to adjust pump motor speed.

The software shall provide a verbose technician/engineering debug output.

The software shall be robust and reliable for a safety-critical system.


2011-03-22: A. Hoag

5.3 MSP430F5438A Notes

5.3.1 ADC

The analog-to-digital component of the microcontroller can sample at a maximum rate of 200

kilo-samples per second at 12-bit resolution [0-4095].

5.3.2 Timers and Interrupts

Table 5.2: Timers and Interrupts

Timer/Interrupt Description

ADC Timer Timer for ADC sampling.

ADC Interrupt Interrupt after sampling and conver-

sion is complete.

Motor PWM Timer Timer for motor PWM signal.

AMB PWM Timers Timers for AMB signals.

5.3.3 TI Provided Code

The software system makes use of two portions of code provided by Texas Instruments.

HAL_PMM, which provides functions to change the power level is located in HAL_PMM.h

and HAL_PMM.c. HAL_UCS provides functions to set system clocks and make use of the

FLL. This is located in HAL_UCS.h and HAL_UCS.c.

5.4 Software Design

5.4.1 Software Subsystem Identification

The software has been split into several subsystems based on common functionality. This

was done to help segment the code. As the software is written in C and is not object-oriented,

these subsystems should not be thought of as objects in their relationships.

Table 5.3: Software Subsystems and Files

Subsystem Files Role

ADC

adc.h, adc.c Analog to Digital Converter – controls setup and

sampling of analog to digital conversions for the

HESAs

AMB

amb.h, amb.c Active Magnetic Bearing – Controls PWM signal

generation for the active magnetic bearing h-

bridges.

Buttons buttons.h, buttons.c Control of the user interface buttons.

Clock clock.h, clock.c Setup and control of the MSP430 master clock,

sub-master clock, and auxiliary clock


2011-03-22: A. Hoag

Subsystem Files Role

GPIO gpio.h, gpio.c Setup and control over the general purpose I/O.

LCD lcd.h, lcd.c Display driver – allows text/graphics to be printed

to the display

Motor motor.h, motor.c Controls PWM signal generation for the 3-phase

motor. (PHX-35 controller)

PID pid.h, pid.c Structure and calculations for a PID loop.

UART uart.h, uart.c Controls serial to USB.

UI ui.h, ui.c Overall user interface control, up a level from

buttons and LCD.

A description of each function within each of the subsystems is detailed in Table 5.4 below.

A common format for functions has been implemented, with the subsystem name and an

underscore preceding the function name. In the descriptions it is explicitly mentioned where

the functions are called from. For example, all “init” functions are called during initializa-

tion, and certain functions, such as “amb_run” are called from within the timer ISR.

Table 5.4: Subsystem Functions

Subsystem Function Description/Parameters/Returns

ADC

adc_init Initialization function: one-time init for ADC hardware To be

called on startup before adc_config and adc_capture_hesa.

Parameters: none

Returns: void

adc_config ADC configuration, can be changed at any time after adc_init

Parameters: [in] mode – The mode to use,

ADC_MODE_SINGLE or ADC_MODE_SEQ

Returns: void

adc_capture_hesa Function to trigger a full capture of HESA values

Parameters: none

Returns: void

AMB

amb_init Initialization function for the AMB control subsystem. Called

on startup

Parameters: none

Returns: void


2011-03-22: A. Hoag


amb_start_lev Function to start levitation of the AMBs. Starts up timer for

ADC and PID calculations.

Parameters: none

Returns: void

amb_stop_lev Function to stop levitation of the AMBs

Parameters: none

Returns: void

amb_run Function that updates AMB with new PID values. Called au-

tomatically by timer ISR

Parameters: none

Returns: void

Buttons

buttons_init Initalization function that sets up the hardware for the buttons.

Called on startup

Parameters: none

Returns: void

Clock

clock_init Initalizes the MSP PMM and clocks (MCLK, SMCLK, and

ACLK). Called on startup

Parameters: none

Returns: void

GPIO

gpio_init Initialize all pins agnostic to other module initializations. All

unused ports are set to outputs with value of logic low

Parameters: none

Returns: void

Motor

motor_init This initalization function sets up the hardware and is called on

startup.

Parameters: none

Returns: void

motor_set_speed This function sets the motor speed.

Parameters: speed (in percentage 0-100)

Returns: void

motor_stop This function stops the motor.

Parameters: none

Returns: void


2011-03-22: A. Hoag


PID

pid_init This initialization function must be used on a pid_t type before

making calculations.

Parameters: [in] pid: pointer to pid_t type

[in] p: proportional initial value

[in] i: integral initial value

[in] d: derivative initial value

Returns: void

pid_compute This function returns a PID calculation when passed the error

and time.

Parameters: [in] pid: Pointer to PID structure used

[in] e: Error

[in] t: Time delta

Returns: float PID: calculated value

UART

uart_init Initialization function for UART that is called on startup.

Parameters: none

Returns: void

uart_putBytes Function to put a byte array to the UART.

Parameters: [in] byte_arr: Byte array of data

[in] length: Length of array

UI

ui_init Initialization function for the UI, to be called on startup

Parameters: none

Returns: void

ui_startup Displays RIT logo, startup info, and plays startup jingle

Parameters: none

Returns: void

ui_buzzTone Function to buzz a tone

Parameters: [in] tone: Tone to play in Hz

Returns: void

ui_buzzClick Function to play "click" used for feedback on buttons

Parameters: none

Returns: void

ui_mainLoop Main loop for UI processing, called by main program loop

Parameters: none

Returns: void


2011-03-22: A. Hoag

Figure 5.3: File Includes Hierarchy

5.4.2 System States and Modes

There are 5 system states: Initializing, Operational, Maintenance, Degraded, and Faulted.

Important: As of 2011-03-22, the state machine has not been fully implemented. In particular, imple-mentations for degraded and faulted are not complete. This will require additional software changes to system-wide flags and likely a refactored state machine pattern.

Initializing Description: The initializing state

Conditions: Device powered on or manual reset (on PCB)

Operation: Microcontroller initializes all drivers for hardware functionality.

(Startup tone/RIT logo are last steps of initialization.)

Operational Description: The system enters the operational state when the pump is fully oper-

able.

Conditions: Initialization is successful.

Operation: Regular system operation.

Maintenance Description: The maintenance state is used for debugging and configuration by an

authorized technician.

Conditions: Technician connects to pump via USB debug port and enables the

maintenance mode.

Operation: Debug information is passed between controller and PC. Pump con-

tinues to operate.


2011-03-22: A. Hoag

Degraded Description: The system enters the degraded state when the pump is operable, but

is at risk of entering the faulted state.

Conditions: Low battery, critical battery

Operation: Alert operator via buzzer, warning LED, and display degraded in-

formation on LCD. Pump continues to operate.

Faulted Description: The system enters the faulted state when the pump cannot operate

(levitation or rotation)

Conditions: Front DRV fault flag raised, rear DRV fault flag raised. (DRV fault

flag is raised when power is under voltage [12V], or over tempera-

ture.)

Operation: Attempt reset on faulted DRV(s). Alert operator via buzzer, fault

LED, and display fault information on LCD.

5.4.3 Clocks and Timers

The MSP430F5438A uses a 32.768kHz clock. Using the MSP FLL (HAL_UCS as men-

tioned in 5.3.3), the frequency can be increased up to a maximum of 25MHz. The SMCLK

and ACLK are used by many of the MSP components in the system.

Table 5.5: System Clocks

Clock Frequency

MCLK 20 MHz

SMCLK MCLK = 20 MHz

ACLK MCLK/4 = 5 MHz

Table 5.6: System Timers

Timer Name Frequency Normal Duty Cycle Range

A0 AMB FX, RX,

FX, FY 20 kHz ~30% - 80%

B PHX-35 motor

controller 50 Hz ~5 - 10%

A1 Buzzer Varies with tone 50%

ADC ADC sample all 5 kHz N/A


2011-03-22: A. Hoag

5.4.4 Overview of System Activity

The diagram shown in Figure 5.4: System Activity Diagram shows the initialization se-

quence, the main loop, and asynchronous interrupts for UART input, button pressed, and

ADC complete. Note that the ADC is launched by a 200ns timer.

Figure 5.4: System Activity Diagram


2011-03-22: A. Hoag

6 Documentation Standards

This document conforms to ISO 690:2010 for citations.

This document conforms to ISO 8601:2004 for time and date formats.

This document has elements based on IEEE 1471/ISO 42010:2007.

In the case that further development of this document continues, these standards should be

reviewed and followed whenever possible.


2011-03-22: A. Hoag

7 References

1. Gomez, Arnold D. Control of a magnetically levitated ventricular assist device. Rochester Institute of Technology. 2009.

2. Wikipedia. PID Controller. [Online] http://en.wikipedia.org/wiki/PID_controller.

3. Khare, Aditi. Estimation and control of the pump pressure rise and flow from intrinsic parameters for a magnetically-levitated axial blood pump. Rochester Institute of Technology. 2008.

P11021: LVAD Software System - EDGEedge.rit.edu/content/P11021/public/design/software... · The...

Documents

Transcript of P11021: LVAD Software System - EDGEedge.rit.edu/content/P11021/public/design/software... · The...