Future Technology Devices International Ltd VMusic SPI Application Note Document Reference No.: FT_000029 Version 1.01 Issue Date: 2008-06-02 Future Technology Devices International Ltd (FTDI) 373 Scotland Street, Glasgow G5 8QB United Kingdom Tel.: +44 (0) 141 429 2777 Fax: + 44 (0) 141 429 2758 E-Mail (Support): [email protected] Web: http://www.ftdichip.com Vinculum is part of Future Technology Devices International Ltd. Neither the whole nor any part of the information contained in, or the product described in this manual, may be adapted or reproduced in any material or electronic form without the prior written consent of the copyright holder. This product and its documentation are supplied on an as-is basis and no warranty as to their suitability for any particular purpose is either made or implied. Future Technology Devices International Ltd will not accept any claim for damages howsoever arising as a result of use or failure of this product. Your statutory rights are not affected. This product or any variant of it is not intended for use in any medical appliance, device or system in which the failure of the product might reasonably be expected to result in personal injury. This document provides preliminary information that may be subject to change without notice. No freedom to use patents or other intellectual property rights is implied by the publication of this document. Future Technology Devices International Ltd, 373 Scotland Street, Glasgow G5 8QB United Kingdom. Scotland Registered Number: SC136640 © Copyright 2008 Future Technology Devices International Ltd Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 Table of Contents 1 Introduction............................................................................................. 4 2 Requirements.......................................................................................... 5 2.1 Hardware ..............................................................................................................5 2.2 Firmware ..............................................................................................................6 2.3 Software ...............................................................................................................6 3 SPI Interface Module .............................................................................. 7 3.1 Pin Definitions .....................................................................................................7 3.2 External Functions ..............................................................................................7 3.2.1 spiInit ....................................................................................................................................... 8 3.2.2 spiReadWait ............................................................................................................................ 8 3.2.3 spiRead.................................................................................................................................... 8 3.2.4 spiWrite.................................................................................................................................... 8 3.3 Internal Functions ...............................................................................................9 3.3.1 spiXfer...................................................................................................................................... 9 3.3.2 spiDelay ................................................................................................................................. 10 4 Command Monitor Module................................................................... 11 4.1 External Functions ............................................................................................11 4.1.1 monSendByte ........................................................................................................................ 11 4.1.2 monCmdSend........................................................................................................................ 12 4.1.3 monCmdSendByteParam...................................................................................................... 12 4.1.4 monCmdSendParam ............................................................................................................. 12 4.1.5 monResponse........................................................................................................................ 12 4.1.6 monPrompt ............................................................................................................................ 13 4.2 Internal Functions .............................................................................................13 5 Program Control ................................................................................... 14 5.1 Initialisation........................................................................................................14 6 Summary ............................................................................................... 16 7 Copyright and Disclaimer .................................................................... 17 8 Contact Information.............................................................................. 18 © Copyright 2008 Future Technology Devices International Ltd 1 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 List of Tables Table 1.1 Button Functions ............................................................................................................................ 4 Table 2.1 VMusic2 Connections..................................................................................................................... 6 Table 2.2 PICDEM 2 PLUS Connections........................................................................................................ 6 © Copyright 2008 Future Technology Devices International Ltd 2 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 List of Figures Figure 2.1 VMusic SPI Application Demo Hardware .................................................................................... 5 Figure 3.1 SPI Data Direction Definition Code.............................................................................................. 7 Figure 3.2 Monitor Callable Functions for SPI Interface.............................................................................. 7 Figure 3.3 SPI Pin Definition Code................................................................................................................. 7 Figure 4.1 Monitor Response Enumeration ................................................................................................ 11 Figure 5.1 Synchronisation with Echo Commands.................................................................................... 14 Figure 5.2 Change to Short Command Set ................................................................................................. 14 Figure 5.3 Main Control Loop....................................................................................................................... 15 © Copyright 2008 Future Technology Devices International Ltd 3 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 1 Introduction The Vinculum VNC1L IC and firmware libraries provided by FTDI allow embedded systems to easily communicate with USB devices. Using the VNC1L device, microcontrollers can now communicate with a range of USB devices including Bulk Only Mass Storage Class (BOMS), Communication Device Class (CDC), Printer Class, Human Interface Device (HID) class devices and USB hubs. To provide a visual demonstration of the capabilities of the VNC1L using the VMusic2 module, a sample application using a PIC microcontroller demonstration board has been created. This example shows how to use a PICDEM 2 PLUS Demo Board to issue the desired commands to the VNC1L in order to control a VMusic2 module. This application note shows example methods of using the SPI interface to communicate with the VNC1L; sending and receiving data from the firmware command monitor; managing and decoding responses from the command monitor. The application provides simple media player functionality using buttons, potentiometer and the LCD on the PICDEM 2 PLUS Demo Board. The buttons send commands to the VNC1L to control playback and select tracks; the LCD shows elapsed time and file metadata obtained by the VNC1L firmware; the potentiometer adjusts the playback volume. The buttons may perform different functions depending on the length of time they are held. Table 1.1 lists the functions of the buttons. State Button Action Stopped S3 Play S2 Play Random S3 (Long) Next Track S2 (Long) Previous Track S3 (Short) Next Track S2 (Short) Previous Track S3 and S2 (Long) Stop S3 and S2 (Short) Pause S3 and S2 (Short) Play S3 and S2 (Long) Stop Playing Paused Table 1.1 Button Functions Implementation details for programming the SPI bus and communicating with the command monitor are provided. Other functions of the application are not specifically related to the function of the VNC1L device and are left to the user to interpret. © Copyright 2008 Future Technology Devices International Ltd 4 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 2 2.1 Requirements Hardware This application requires a VMusic2 module, a Microchip PICDEM 2 PLUS Demo Board and a cable to connect the VMusic2 and PICDEM 2 PLUS board. A PIC18F452 or PIC18F4520 microcontroller is needed to run the provided code. Figure 2.1 VMusic SPI Application Demo Hardware The connecting cable comprises four I/O port signals and +5V and GND signals. This carries power and the SPI interface signals - SCLK, CS, SDI and SDO. Table 2.1 shows the connection between the CN2 (monitor interface) on the VMusic2 module and the 2mm ribbon cable supplied with the module. In Table 2.2 the port connections where the cable should be connected to on the PICDEM 2 PLUS board are listed. . © Copyright 2008 Future Technology Devices International Ltd 5 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 Pin Number Signal Name Colour Pin Number Signal Name Colour 8 N/A Blue RC2 CS Green 7 N/C RC5 SCLK Yellow 6 CS Green RC1 SDI Orange 5 SCLK Yellow +5V +5V Red 4 SDI Orange RC0 SDO Brown 3 +5V Red GND GND Black 2 SDO Brown 1 GND Black Table 2.2 PICDEM 2 PLUS Connections Table 2.1 VMusic2 Connections The VMusic2 Module must be set to SPI mode using jumper CN3 to connect the UART/SPI pin to GND. J7 and J9 on the PICDEM 2 PLUS board must be unpopulated and J6 populated. The 4MHz canned oscillator, supplied with the board, is required. 2.2 Firmware The VNC1L device on the VMusic2 Module must be programmed with VMSC1 firmware version 3.63 or later for this sample project. All of the VMSC1 firmware commands are specified in the Vinculum Firmware User Manual. 2.3 Software Sample C code for the PIC18F452 or PIC18F4520 microcontroller is available as a free download from the FTDI web site. The code for the PIC microcontroller must be compiled with SourceBoost C or ported to an equivalent compiler before being programmed onto the device. © Copyright 2008 Future Technology Devices International Ltd 6 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 3 SPI Interface Module The SPI Interface module controls the application’s communication with the SPI interface on the VNC1L. The files SPI.c and SPI.h manage the interface as an SPI Master, controlling the SCLK (clock), CS (chip select) and SDI (data in) signals. The SDO (data out) signal is controlled by the VNC1L. The direction of data is encoded in the SPI transaction as either a read or a write. The definitions are shown in Figure 3.1. #define DIR_SPIWRITE 0 #define DIR SPIREAD 1 Figure 3.1 SPI Data Direction Definition Code Each callable function in the SPI Interface Module is aliased using a pre-processor definition to allow the entire module to be replaced by a functionally equivalent module for handling communications. This may be a UART or Parallel FIFO interface. The module is called the Monitor Interface. The definitions are included in the SPI.h file and are shown in Figure 3.2. The calling application should only use the generic interface routine names and not the SPI specific ones. #define #define #define #define #define monInit spiInit monRead spiRead monReadWait spiReadWait monWrite spiWrite monInterrupt Figure 3.2 Monitor Callable Functions for SPI Interface 3.1 Pin Definitions The SPI Interface between the PICDEM 2 PLUS and the VNC1L on the VMusic2 Module utilises 4 signals. All signal names given here are relative to the VNC1L device. The pin definitions for the signals used by the SPI interface are shown in Figure 3.3. #define PORT_SDI #define TRIS_SDI portc.1 trisc.1 // SDI (on VMusic) is RC1 (Port C bit 1) #define PORT_SDO #define TRIS_SDO portc.0 trisc.0 // SDO (on VMusic) is RC0 (Port C bit 0) #define PORT_SCLK portc.5 #define TRIS_SCLK trisc.5 // SCLK is RC5 (Port C bit 5) #define PORT_CS #define TRIS_CS // CS is RC2 (Port C bit 2) portc.2 trisc.2 Figure 3.3 SPI Pin Definition Code 3.2 External Functions The SPI Interface code presents 4 subroutines externally: • spiInit – initialise the SPI interface I/O pins. • spiReadWait – read continually from the SPI interface until a byte is received. • spiRead – check SPI interface for available byte of data. • spiWrite – write a byte of data to the SPI interface. © Copyright 2008 Future Technology Devices International Ltd 7 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 These commands can be used to allow a program to access the VNC1L firmware command monitor. 3.2.1 spiInit Parameters: None. Returns: None. Calls: None. This routine sets up the 4 interface pins SCLK (output), CS (output), SDI (output) and SDO (input). It will also initialise the 3 output signal to a logic low. 3.2.2 spiReadWait Parameters: None. Returns: char – data read from SPI Data Read operation. Calls: spiXfer Repeatedly calls spiXfer to generate an SPI Data Read operation until a byte of data has been received successfully. 3.2.3 spiRead Parameters: char *pSpiData – pointer to variable to receive data read from SPI Data Read operation. Returns: char – zero if data read successful, 1 if unsuccessful. Calls: spiXfer Calls spiXfer subroutine once to generate an SPI Data Read operation. If a byte of data has been received successfully it will return zero, otherwise it will return 1. The calling parameter pSpiData is updated with data read from the SPI interface. 3.2.4 spiWrite Parameters: char spiData – data to write with SPI Data Write operation. © Copyright 2008 Future Technology Devices International Ltd 8 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 Returns: None. Calls: spiXfer Calls spiXfer subroutine once to generate an SPI Data Write operation. If the byte of data has been transmitted successfully it will return, otherwise it will retry. 3.3 Internal Functions The following subroutines are not available externally to the SPI interface code. 3.3.1 spiXfer Parameters: int spiDirection – specifies an SPI read or write operation. char *pSpiData – pointer to variable to receive a byte read from an SPI read operation or pointer to data to transmit with an SPI write operation. Returns: char – zero if data write successful, 1 if unsuccessful. Calls: None. This subroutine generates a state machine to both read and write data on the SPI interface. The direction of data flow is set using the spiDirection parameter using the values in Figure 3.1. The state machine flow is as follows: Create start condition on SPI interface – CS high, SDI high, SCLK rising edge. Set data direction – CS high, SDI set to spiDirection, SCLK rising edge. Set data operation – CS high, SDI set to low, SCLK rising edge. For each 8 bits of data (starting at most significant bit) – If read set bit in data variable to value from SDO signal. If write set SDI to bit value from data variable. Toggle SCLK signal. Read status bit value from SDO signal. Toggle SCLK signal. Set finish condition – CS low, SCLK rising edge. Return status bit value. The spiXfer subroutine is not interrupt driven and does not use the built-in SPI functionality of the microcontroller. It is solely intended to demonstrate an efficient method of reading and writing to the SPI Interface on the VNC1L. © Copyright 2008 Future Technology Devices International Ltd 9 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 3.3.2 spiDelay Parameters: None. Returns: None. Calls: None. A delay function may be added to reduce the speed of the bus operation by defining the spiDelay routine to perform a delay function if it is desired to reduce the SPI interface speed. This is set to produce a nop operation in this example. © Copyright 2008 Future Technology Devices International Ltd 10 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 4 Command Monitor Module The firmware command monitor on the VNC1L interprets commands from an application and reports the status of commands. There are several error responses which can come from each command. The Command Monitor Module controls the sending of commands to the VNC1L, receiving the responses and interpreting the responses. The appropriate subroutines in the Monitor Interface Module are called to communicate with the VNC1L. Figure 4.1 lists the enumeration of responses from the VNC1L firmware command monitor. // Prompts and messages returned by VNC1L in Short Command Set enum vResponse { // Prompts returned by all VNC1L firmware Resp_Prompt_OK, // > (Success) Resp_Prompt_ND, // ND (Success) Resp_Prompt_UE, // E echo Resp_Prompt_LE, // e echo Resp_Prompt_CF, // CF (Command Failed) Resp_Prompt_BC, // BC (Bad Command) Resp_Prompt_DF, // DF (Disk Full) Resp_Prompt_FI, // FI (File Invalid) Resp_Prompt_RO, // RO (Read Only) Resp_Prompt_FO, // FO (File Open) Resp_Prompt_NE, // NE (Dir Not Empty) Resp_Prompt_FN, // FN (Filename Invalid) Resp_Prompt_End, // Asynchronous messages returned by VMSC1 firmware Resp_Message_P, // P / Playing Resp_Message_S, // S / Stopped Resp_Message_T, // T / Time // Asynchronous messages returned by all VNC1L firmware Resp_Message_NU, // NU / No Upgrade Resp_Message_DD1, // DD1 / Device Detected USB Port 1) Resp_Message_DD2, // DD2 / Device Detected USB Port 2) Resp_Message_DR1, // DR1 / Device Removed USB Port 1) Resp_Message_DR2, // DR2 / Device Removed USB Port 2) Resp_Message_Splash, // Ver ... Resp_None = 0xff, }; Figure 4.1 Monitor Response Enumeration 4.1 4.1.1 External Functions monSendByte Parameters: char monData – byte of data to write to interface. Returns: None. Calls: monWrite() This command simply transfers a byte of data to the Monitor Interface Module. It has an inline specifier due to the simplicity of the function. © Copyright 2008 Future Technology Devices International Ltd 11 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 4.1.2 monCmdSend Parameters: char monCmd – command byte to write to interface. Returns: None. Calls: monWrite() This command writes the command byte passed as a parameter to the Monitor Interface Module. It follows the command byte with a carriage return character if required. 4.1.3 monCmdSendByteParam Parameters: char monCmd – command byte to write to interface. unsigned char monParam – single byte to be sent as parameter. Returns: None. Calls: monWrite() This command writes the command byte passed as a parameter to the Monitor Interface Module. It will then send a space character to delimit the parameter. The single-byte parameter monParam is sent followed by a carriage return. 4.1.4 monCmdSendParam Parameters: char monCmd – command byte to write to interface. unsigned char monCount – count of bytes to send as parameters to interface. unsigned char *pmonParam – pointer to array of bytes to be sent as parameters. Returns: None. Calls: monWrite() This command writes the command byte passed as a parameter to the Monitor Interface Module. It will then send a space character to delimit the parameters. The parameters consist of monCount bytes, the data is passed in the pmonParam array. The command and parameters are followed by a carriage return. 4.1.5 monResponse Parameters: None. Returns: © Copyright 2008 Future Technology Devices International Ltd 12 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 enum vResponse – enumeration of prompt or error response command returns. Calls: monRead() After a command has been sent to the VNC1L, it will always return a response indicating success or an error condition. The monResponse subroutine compares the data returned from the command monitor to a list of expected responses and returns a matching value from an enumeration list. This can be used by the calling application to check for the expected behaviour of the device. 4.1.6 monPrompt Parameters: None. Returns: enum vResponse – enumeration of prompt or error response command returns. Calls: monResponse() This will poll the monResponse subroutine until a valid prompt or error message is returned. In the enumeration vResponse, Resp_Prompt_End marks the last valid prompt or error message in the list. Subsequent values indicate asynchronous messages which may be sent by the VNC1L. 4.2 Internal Functions There are no internal functions in the Command Monitor Module. © Copyright 2008 Future Technology Devices International Ltd 13 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 5 Program Control This section describes the sequence of events used by the application to communicate with the VNC1L firmware command monitor. 5.1 Initialisation The first task of the application is to establish a connection to and synchronise with the command monitor. This is best accomplished by sending and receiving echo commands until the state of the command monitor is known. The code in Figure 5.1 repeatedly sends out a capital ‘E’ character followed by a lower-case ‘e’ character until the command monitor echoes the characters back in the same order. // ensure Vinculum is synchronised // ignore all messages and prompts until sync operation completes while (1) { clear_wdt(); monCmdSend('E'); while (monPrompt() != Resp_Prompt_UE); monCmdSend('e'); if (monPrompt() == Resp_Prompt_LE) break; }; Figure 5.1 Synchronisation with Echo Commands Next, the application changes the command monitor to use the Short Command Set. This reduces the length of commands and responses making sending commands and parsing responses easier. The code in Figure 5.2 shows how this is done. An error handling routine is called if the command monitor call is not successful. // change to Short Command Set Mode monCmdSend(CMD_SCS); resp = monPrompt(); if (resp != Resp_Prompt_OK) { opError(resp); } Figure 5.2 Change to Short Command Set After the Short Command Set mode has been selected the code enters the main loop, see Figure 5.3, where it checks for button presses and updates the LCD based on the asynchronous messages returned by the command monitor. It remains in this loop until the disk containing the media files is removed. © Copyright 2008 Future Technology Devices International Ltd 14 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 do { clear_wdt(); resp = monResponse(); if (resp == Resp_Message_P) { rspPlaying(); opStatus.STATUS_PLAY = 1; opStatus.STATUS_WAITPROMPT = 0; opStatus.STATUS_RESET = 1; } else if (resp == Resp_Message_T) { rspTime(); opStatus.STATUS_PLAY = 1; } else if (resp == Resp_Message_S) { rspStopped(); opStatus.STATUS_PLAY = 0; } else if (resp == Resp_Prompt_ND) { // device removed - no action } else if (resp == Resp_Prompt_OK) { // no idle processing until prompt received opStatus.STATUS_WAITPROMPT = 0; } else if (resp == Resp_None) { opControl(); } opStatus(); // if disk is removed detect this and loop back // to No Disk message } while (resp != Resp Prompt ND); Figure 5.3 Main Control Loop © Copyright 2008 Future Technology Devices International Ltd 15 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 6 Summary The provided C code for a PIC microcontroller demonstrates how to use the SPI Interface and Command Monitor to interface with a VMusic2 Module. The techniques used in this application note are applicable to the whole range of VNC1L-based modules and applications. © Copyright 2008 Future Technology Devices International Ltd 16 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 7 Copyright and Disclaimer © Copyright 2008 Future Technology Devices International Limited Version 1.01 Initial Datasheet Created May 2008 This document provides preliminary information that may be subject to change without notice. Vinculum is part of Future Technology Devices International Limited. Neither the whole nor any part of the information contained in, or the product described in this datasheet, may be adapted or reproduced in any material or electronic form without the prior written consent of the copyright holder. This product and its documentation are supplied on an as-is basis and no warranty as to their suitability for any particular purpose is either made or implied. Future Technology Devices International Limited will not accept any claim for damages howsoever arising as a result of use or failure of this product. Your statutory rights are not affected. This product or any variant of it is not intended for use in any medical appliance, device or system in which the failure of the product might reasonably be expected to result in personal injury. This document provides preliminary information that may be subject to change without notice. No freedom to use patents or other intellectual property rights is implied by the publication of this document. Future Technology Devices International Limited, 373 Scotland Street, Glasgow G5 8QB, United Kingdom. Scotland Registered Number: SC136640. © Copyright 2008 Future Technology Devices International Ltd 17 Document Reference No.: FT_000029 VMusic SPI Application Note Version 1.01 Clearance No.: FTDI# 35 8 Contact Information Head Office – Glasgow, UK Future Technology Devices International Limited 373 Scotland Street Glasgow G5 8QB United Kingdom Tel: +44 (0) 141 429 2777 Fax: +44 (0) 141 429 2758 E-mail (Sales) [email protected] E-mail (Support) [email protected] E-mail (General Enquiries) [email protected] Web Site URL http://www.ftdichip.com Web Shop URL http://www.ftdichip.com Branch Office – Taipei, Taiwan Future Technology Devices International Limited (Taiwan) 4F, No 18-3, Sec. 6 Mincyuan East Road Neihu District Taipei 114 Taiwan, R.O.C. Tel: +886 (0) 2 8791 3570 Fax: +886 (0) 2 8791 3576 E-mail (Sales) [email protected] E-mail (Support) [email protected] E-mail (General Enquiries) [email protected] Web Site URL http://www.ftdichip.com Branch Office – Hillsboro, Oregon, USA Future Technology Devices International Limited (USA) 7235 NW Evergreen Parkway, Suite 600 Hillsboro, OR 97123-5803 USA Tel: +1 (503) 547 0988 Fax: +1 (503) 547 0987 E-Mail (Sales) [email protected] E-Mail (Support) [email protected] Web Site URL http://www.ftdichip.com Distributor and Sales Representatives Please visit the Sales Network page of the FTDI Web site for the contact details of our distributor(s) and sales representative(s) in your country. © Copyright 2008 Future Technology Devices International Ltd 18