MSP430
USB Developers Package 3.20.00 Release Notes
This release note is divided into the following sections:
Introduction
MSP430 USB Developers Package Version 3.20.00 is a full release with
support for CDC, HID, MSC, PHDC and composite devices.
MSP430 USB Developers Package provides APIs that make it easy to
implement a simple USB data connection between an MSP430 and a USB
host. It includes support for these common USB device classes:
• Communications Device Class (CDC)
• Human Interface Device class (HID)
• Mass Storage Class (MSC)
• Personal Healthcare Device Class (PHDC)
A user of previous releases 3.00.00 or after require minimal changes to the
application. Users of 1.00.00.05 need to update their
applications. They must read the “Updating
and Compatibility Information” below, and follow the instructions to
port their application to this new release.
back to
top
Documentation
A complete Programmer’s Guide is provided with this release.
Please reference it for all information concerning the API stacks and
Descriptor Tool.
Programmers_Guide_MSP430_USB_API
back to
top
What's New
MSP430 USB Developers Package 3.20.00 Release (this release).
- Updated to use BSD license.
- New Java based version of the
HID Demo software. You will need JDK 6.1+ installed to run this new HID
demo. For more details see ./hidDemo-java/release_notes.html
- Bug Fixes
Defects Fixed in v3.20.00:
1159 - |
Need to update text headers in USB API source files |
2127 |
USBMSC_poll should return kUSBMSC_processBuffer instead of kUSBMSC_okToSleep in one more place |
back to
top
Upgrading and Compatibility Information
This release has many significant changes from MSP430 USB Developers
Package 1.00.00.05. It is important to understand the
information below in order to successfully use this release.
Porting instructions for CCS based project from 1.00.00.05 to 3.10.00
- Make a BACKUP of your old
application. This is important as we will refer to files in the BACKUP
later.
- Close CCS if open.
- Remove the
following directories from your project folder - Common, USB_CDC_API,
USB_HID_API, USB_Common.
- If your project
contains folders F550x and F552x, then these directories MUST be
deleted. The previous example sets included a separate CCS build
configuration for each device family, and thus included these
directories. However CCS now makes it very easy to move a
project from one device to another; instructions are included at the
end of this section.
- File
msp430f5529.cmd MUST be deleted from the project. The previous
1.00.00.05 version of the product shipped device-specific cmd and ccxml
files. These files may be deleted. CCS-provided files are used in
v3.10.00. Note the nk_msp430f5529.cmd may have to added back manually.
- Delete
USB_constructs.c and USB_constructs.h
- Copy the following
folders from v3.10.00 install into your project folder – “USB_API” and
“F5xx_F6xx_Core_Lib”. These folders and files are present in ALL CDC
and HID examples. Their content from example to example is
identical, so they can be copied from any of the examples (for example,
C1_example).
- Copy
usbConstructs.c and usbConstructs.h into your project. Merge any
changes to USB_constructs.c that were made in BACKUP to usbConstructs.c.
- Copy msp430USB.cmd
into your project.
- Copy usbEventHandling.c into your project. Merge any
changes made in usb_eventHandling.c from BACKUP.
- Create a new folder called “USB_config” within your
project. (This folder can have a different name, but the API’s
documentation refers to this folder as “USB_config”.) This
folder will contain the Descriptor Tool output generated in the next
step.
- Run the Descriptor Tool in v3.10.00. Open the *.dat file
from the BACKUP. This file can be saved by the Descriptor Tool,
allowing the inputs to be re-loaded into the GUI at a later time for
re-generation of the output files. If the *.dat file is missing, you
will need to manually input the Descriptor Tool settings.
- Save a new *.dat file (File->SaveAs) in your
application. It can be used to easily move to new versions of the
Descriptor Tool in the future.
- Press the “Generate Output” button to generate new source
files. Place them into the newly created “USB_config”
directory. NOTE: If creating an HID-Traditional device,
descriptor.c and descriptor.h will need some information migrated from
the BACKUP versions – see the Programmer’s Guide’s chapter on creating
HID-Traditional devices.
- Open your project in CCS.
- Before building the project, you will need to set the
following include paths in Project->Properties->C/C++
Build->MSP430 Compiler->Include Options. These
are required to compile any project using this API. NOTE: You
will need to set these paths one by one, by clicking on the green plus.
${PROJECT_ROOT}
${PROJECT_ROOT}/USB_config
${PROJECT_ROOT}/F5xx_F6xx_Core_Lib
- Additionally, the following include paths may
be added, for the application to call the API functions.
${PROJECT_ROOT}/USB_API/USB_Common
${PROJECT_ROOT}/USB_API/USB_CDC_API
${PROJECT_ROOT}/USB_API/USB_HID_API
${PROJECT_ROOT}/USB_API/USB_MSC_API
- You may need to change some include paths in your
application source files, as per the new directory structure. You might
choose to eliminate all paths from your include statements and use
include paths in your project settings as described above. Here is a
mapping of the changes that may be required.
Old Include Paths |
New
Include Paths |
#include "Common\device.h" |
#include
"USB_API/USB_Common/device.h"
OR
#include "device.h" (1) |
#include "Common\types.h" |
#include "USB_API/USB_Common/types.h"
OR
#include "types.h" (1) |
#include
"USB_Common\descriptors.h" |
#include
"descriptors.h" |
#include "USB_Common\usb.h" |
#include
"USB_API/USB_Common/usb.h"
OR
#include "usb.h" (1) |
#include "Common\hal_UCS.h" |
#include
"HAL_UCS.h" (2) |
#include "Common\hal_pmm.h" |
#include
"HAL_PMM.h" (2) |
#include "USB_CDC_API\UsbCdc.h" |
#include
"USB_API/USB_CDC_API/UsbCdc.h"
OR
#include "UsbCdc.h" (1) |
#include "USB_HID_API\UsbCdc.h" |
#include
"USB_API/USB_HID_API/UsbHid.h"
OR
#include "UsbHid.h" (1) |
#include "Usb_constructs.h" |
#include
"usbConstructs.h" |
(0) Note the change from
backslashes to forward-slashes
(1) Needs step 17 above
(2) Note the change from lower case to upper
case
- Change the following function calls.
Old |
New |
hid_sendDataWaitTilDone() |
hidSendDataWaitTillDone() |
hid_sendDataInBackground() |
hidSendDataInBackground() |
hid_receiveDataInBuffer() |
hidReceiveDataInBuffer() |
cdc_sendDataWaitTilDone() |
cdcSendDataWaitTilDone() |
cdc_sendDataInBackground() |
cdcSendDataInBackground() |
cdc_receiveDataInBuffer() |
cdcReceiveDataInBuffer() |
- Change the following values in source
files.
XT1LFOFFG = 0
XT1HFOFFG = 0
- Now rebuild the project.
Porting instructions for IAR based project from 1.00.00.05 to 3.10.00
- Make a BACKUP of
your old application. This is important as we will refer to files in
the BACKUP later.
- Close IAR if open.
- Remove the
following directories from your project folder - Common, USB_CDC_API,
USB_HID_API, USB_Common.
- Delete
USB_constructs.c and USB_constructs.h
- Copy the following
folders from v3.10.00 install into your project folder – “USB_API” and
“F5xx_F6xx_Core_Lib”. These folders and files are present in ALL CDC
and HID examples. Their content from example to example is
identical, so they can be copied from any of the examples (for example,
C1_example).
- Copy
usbConstructs.c and usbConstructs.h into your project. Merge any
changes to USB_constructs.c that were made in BACKUP to usbConstructs.c.
- Copy
usbEventHandling.c into your project. Merge any changes made in
usb_eventHandling.c from BACKUP.
- Create a new
folder called “USB_config” within your project. (This folder can have a
different name, but the API’s documentation refers to this folder as
“USB_config”.) This folder will contain the Descriptor Tool
output generated in the next step.
- Run the Descriptor
Tool in v3.10.00. Open the *.dat file from the BACKUP. This file can be
saved by the Descriptor Tool, allowing the inputs to be re-loaded into
the GUI at a later time for re-generation of the output
files. If the *.dat file is missing, you will need to
manually input the Descriptor Tool settings.
- Save a new *.dat file (File->SaveAs) in your
application. It can be used to easily move to new versions of the
Descriptor Tool in the future.
- Press the “Generate Output” button to generate new source
files. Place them into the newly created “USB_config”
directory. NOTE: If creating an HID-Traditional device,
descriptor.c and descriptor.h will need some information migrated from
the BACKUP versions – see the Programmer’s Guide’s chapter on creating
HID-Traditional devices.
- Open your project in IAR. Clean up your
project. Delete old directories - Common, USB_common,
USB_CDC_API, USB_HID_API. Add new ones - USB_API, USB_config,
F5xx_F6xx_Core_Lib. Add files - usbConstructs.c and
usbEventHandling.c.
- Before building the project you will need to set the
following include paths in Project->Options->C/C++
Compiler->Preprocessor->Additional Include Directories:
These are required to compile any project using this API.
$PROJ_DIR$
$PROJ_DIR$/USB_config
$PROJ_DIR$/F5xx_F6xx_Core_Lib
- Additionally the following include paths may be
added, for the application to call the API functions.
$PROJ_DIR$/USB_API/USB_Common
$PROJ_DIR$/USB_API/USB_CDC_API
$PROJ_DIR$/USB_API/USB_HID_API
$PROJ_DIR$/USB_API/USB_MSC_API
- You may need to change some include paths in
your application source files as per the new directory structure. You
might choose to eliminate all paths from your include statements and
use include paths in your project settings as described above. Here is
a mapping of the changes that may be required.
Old Include Paths |
New
Include Paths |
#include "Common\device.h" |
#include
"USB_API/USB_Common/device.h"
OR
#include "device.h" (1) |
#include "Common\types.h" |
#include "USB_API/USB_Common/types.h"
OR
#include "types.h" (1) |
#include
"USB_Common\descriptors.h" |
#include
"descriptors.h" |
#include "USB_Common\usb.h" |
#include
"USB_API/USB_Common/usb.h"
OR
#include "usb.h" (1) |
#include "Common\hal_UCS.h" |
#include
"HAL_UCS.h" (2) |
#include "Common\hal_pmm.h" |
#include
"HAL_PMM.h" (2) |
#include "USB_CDC_API\UsbCdc.h" |
#include
"USB_API/USB_CDC_API/UsbCdc.h"
OR
#include "UsbCdc.h" (1) |
#include "USB_HID_API\UsbCdc.h" |
#include
"USB_API/USB_HID_API/UsbHid.h"
OR
#include "UsbHid.h" (1) |
#include "Usb_constructs.h" |
#include
"usbConstructs.h" |
(0) Note the change from
backslashes to forward-slashes
(1) Needs step 17 above
(2) Note the change from lower case to upper
case
- Change the following function calls.
Old |
New |
hid_sendDataWaitTilDone() |
hidSendDataWaitTillDone() |
hid_sendDataInBackground() |
hidSendDataInBackground() |
hid_receiveDataInBuffer() |
hidReceiveDataInBuffer() |
cdc_sendDataWaitTilDone() |
cdcSendDataWaitTilDone() |
cdc_sendDataInBackground() |
cdcSendDataInBackground() |
cdc_receiveDataInBuffer() |
cdcReceiveDataInBuffer() |
- Change following values in source
files.
XT1LFOFFG = 0
XT1HFOFFG = 0
- Now rebuild the project.
Other CCS specific considerations
- Porting to a different
device. The example projects provided in this product are
pre-configured for the MSP430F5529 device. The projects are
designed to be very easily adapted to any other USB-equipped MSP430,
simply by changing the selected device in the project’s options --
follow these steps.
- Open the project in CCS
- Go to
Project->Properties->CCS Build. Select the device from
the drop-down menu and click “Apply”. Select "Create a new build
configuration initialized with build options from the existing
configuration". Select a new name for this configuration and
make it active if needed.
- NOTE: Please edit the
Project->Properties->C/C++ Build->MSP430
Compiler->Predefined Symbols to include ONLY ONE device define
of format __MSP430Fxxx__. Having more than one will result in
improper compilation and/or operation.
Other IAR specific considerations
- The example projects provided in this
product are pre-configured for the MSP430F5529 device. The
projects are designed to be very easily adapted to any other
USB-equipped MSP430, simply by changing the selected device in the
project’s options -- follow these steps.
- Open the project in IAR
- Go to Project->Options->General Options->Target
and change the device.
- When the USB API is built into a
library, and an application is built against the library,
iUsbInterruptHandler gets optimized out by IAR Linker. To WORKAROUND
this problem add “-giUsbInterruptHandler” as part of linker options.
- n IAR, the environment
gives a choice of using the DLIB standard library, or the legacy
CLIB. To compile the API stacks, DLIB must be selected.
back to top
Host Support
Supported Operating Systems on the USB host:
- Windows 7 (32bit and 64
bit), Windows XP, Vista
-
Ubuntu version 9.04
- Mac OS
back to top
Hardware
Supported devices
- The MSP430 USB API supports
all USB-equipped MSP430 devices:
- MSP430F552x/551x
- MSP430F550x (note that this includes the F5510)
- MSP430F563x/663x
- The API automatically adapts to any
selected device, based on the CCS/IAR project’s options.
- If using a device other than the
“flagship” device in each family (that is, the F5638, F6638, F5529, or
F5510): The examples contain a function Init_Ports() which
initializes all unused port I/Os; this avoids excess power draw
resulting from floating inputs. However, devices other than
the flagship device may contain less I/Os than the flagship.
If compiling for one of these devices, some of the initializations in
this function may generate an error. The offending lines can
simply be commented-out.
- See
http://www.ti.com/msp430usb for more information on these devices.
Boards
- The examples should build
and run on any hardware based on an USB-equipped MSP430, provided it is
properly implemented. However, special concern should be paid
to the I/O initializations in Init_Ports(). The examples were
primarily designed to run on MSP430 FET target boards – for example,
the TS430PN80USB for the MSP430F5529. All the examples
include a function Init_Ports(), which initializes the unused port
I/Os; this avoids excess power draw resulting from floating
inputs. However, doing so makes this function specific to
MSP430 FET target boards. If using other hardware, this
function may need to be modified.
- Some of the MSC API examples
are designed to run on the MSP430F5529 Experimenters’ board -
MSP-EXP430F55529. This is because they require the SD-card
interface on this board.
back to top
IDEs and Compiler
- Code Composer Studio Version: 4.2.0.10018 with MSP430 C/C++ Compiler v3.3.1. All examples can compile within the 16K-limited
free version.
- IAR Embedded Workbench for
MSP430 5.10 with IAR C/C++ Compiler V5.20.1.50215/W32. Works with either the free, 8K-limited IAR
Kickstart or a fully-licensed version; however, the MSC API does not
fit within 8K and therefore requires a fully-licensed version.
- SYSBIOS v6.32.01.38 and XDCTOOLS v3.22.01.20
back to top
Known Issues
None
back to top
Benchmarks
Size Benchmarks
Code Composer Studio
Test Name |
RAM (B) |
FLASH (B) |
CCS\C1_bench |
254 |
5,920 |
CCS\CC1_bench |
288 |
6,186 |
CCS\CH1_bench |
346 |
8,155 |
CCS\CHM1_bench |
880 |
13,697 |
CCS\H1_bench |
312 |
5,829 |
CCS\HH1_bench |
336 |
6,072 |
CCS\M1_bench |
704 |
8,930 |
IAR Workbench
Test Name |
RAM (B) |
FLASH (B) |
IAR\C1_bench |
269 |
5,279 |
IAR\CC1_bench |
303 |
5,517 |
IAR\CH1_bench |
358 |
7,130 |
IAR\CHM1_bench |
880 |
11,933 |
IAR\H1_bench |
316 |
5,335 |
IAR\HH1_bench |
341 |
5,565 |
IAR\M1_bench |
698 |
7,941 |
Note: Special benchmark application used.
IAR compiler optimization option used is high and balanced
CCS compiler optimization opton used is --opt_level = 3.
MSC Performance (Double Buffering)
Block Size | Read (mb/sec) | Write (mb/sec) |
4096 | 0.20 | 0.18 |
8192 | 0.22 | 0.18 |
16284 | 0.23 | 0.16 |
32768 | 0.24 | 0.18 |
65536 | 0.24 | 0.15 |
131072 | 0.23 | 0.17 |
262144 | 0.24 | 0.19 |
524288 | 0.24 | 0.19 |
MSC Performance
Block Size | Read (mb/sec) | Write (mb/sec) |
4096 | 0.14 | 0.14 |
8192 | 0.19 | 0.18 |
16284 | 0.19 | 0.17 |
32768 | 0.19 | 0.18 |
65536 | 0.19 | 0.17 |
131072 | 0.19 | 0.18 |
262144 | 0.19 | 0.18 |
524288 | 0.19 | 0.17 |
Note: VDBENCH application used for MSC benchmarking.
CDC Performance
Direction
|
Speed
|
CPU Freq
|
RX
|
99.917KBps
|
1.000MHz
|
RX
|
197.082KBps
|
2.000MHz
|
RX
|
340.978KBps
|
4.000MHz
|
RX
|
511.363KBps
|
8.000MHz
|
RX
|
510.828KBps
|
12.000MHz
|
RX
|
511.550KBps
|
16.000MHz
|
RX
|
511.663KBps
|
20.000MHz
|
RX
|
511.538KBps
|
25.000MHz
|
TX
|
77.723KBps
|
1.000MHz
|
TX
|
157.463KBps
|
2.000MHz
|
TX
|
258.933KBps
|
4.000MHz
|
TX
|
511.376KBps
|
8.000MHz
|
TX
|
511.825KBps
|
12.000MHz
|
TX
|
511.813KBps
|
16.000MHz
|
TX
|
512.000KBps
|
20.000MHz
|
TX
|
512.000KBps
|
25.000MHz
|
Note: Tranfer size for CDC benchmarks is 2048 arrays with 1024bytes/array
back to top
Versioning
All releases have 4 digits (M.mm.pp.bb). This includes GA and
pre-releases (engineering, alpha/EA, beta, etc.). Pre-releases are
denoted with a suffix (e.g. 6.30.00.00-eng or 6.30.00.10-beta).
This product's version follows a version format, M.mm.pp.bb, where M is
a single digit Major number, mm is 2 digit minor number, pp is a 2
digit patch number, and b is an unrestricted set of digits used as an
incrementing build counter.
To support multiple side-by-side installations of the product, the
product version is encoded in the top level directory (e.g.
MSP430_USB_Developers_Package_3_0_0_0).
Subsequent releases of patch upgrades will be identified by the patch
number, ex. 3.0.1.05 with directory
MSP430_USB_Developers_Package_3_0_1_05. Typically, these patches only
include critical bug fixes.
back to top
Technical Support and Product Updates
back to top
Last updated: March 10, 2011