PROTEUS USB SIMULATION

Introduction

Proteus VSM USB simulation represents the worlds first schematic based embedded USB simulation engine and is currently supported with the following microcontroller variants:

PIC18F2450, PIC18F2455, PIC18F2458, PIC18F2550, PIC18F2553, PIC18F4450, PIC18F4455, PIC18F4458, PIC18F4550, PIC18F4553, PIC18F13K50, PIC18F14K50, PIC18LF13K50, PIC18LF14K50, and Atmel AT90USB1286, AT90USB646.

Datasheets for these devices can be viewed by clicking on appropriate device name, above. Note that there are a number of Errata datasheets for these devices which are are available directly from Arizona Microchip’s website: http://www.microchip.com/.

Please check the Arizona Microchip website for the latest information and errata on particular devices.

USB Simulation in Proteus is enabled by installing the Labcenter USB drivers and then using one of the supported USB microcontrollers. Analysis and debugging of USB traffic is enabled via the purchase of the USB Transaction Analyser – a seperately licensed product.

It is highly recommended that you install the drivers on a Virtual Machine to protect your development environment. Installation and setup examples are provided for both VMWare and the XP Virtual Machine provided with Windows 7.

Note that at the time of writing the drivers are only 32-bit and virtual machine usage is therefore the only viable solution for users with 64-bit host computers.

For example, if you had a licence for Proteus VSM for PIC18 then you would be able to enable USB simulation and could simulate PIC18 USB designs. In order to monitor or debug USB communications however, you would need to purchase the Proteus USB Transaction Analyser.

This help file provides some introductory information on USB and then explains how to simulate, test and debug a USB design using Proteus.

See also

An Introduction to USB

Proteus VSM USB Simulation

Working with VMWARE

Working with VirtualPC on Windows 7

Installing the USB Drivers

Running a USB Simulation

Using the USB Transaction Analyser

Writing USB Firmware

This help file last modified 30th November 2012.


An Introduction to USB

AN INTRODUCTION INTO USB

Overview

Nowadays, legacy buses such as RS232 and parallel port are becoming become more and more rare. The engineering drive is to eliminate mutually incompatible bus architectures by introducing a universal bus. Undoubtedly the most common of these is USB – The Universal Serial Bus.

The USB bus architecture allows the creation of a multitude of distinct device types – serial and parallel ports, sound cards, mass storage devices (USB drives), human interface devices (mice and keyboards), etc.

This flexibility is possible due to the depth of software and hardware support. In contrast to legacy buses the USB bus requires a complex multi-layer protocol to support the necessary diversity of devices. Fortunately however, there exist named USB Frameworks (both commercial and free open-source), which do most of the USB-related work – see Writing USB Firmware for more information.

The following discussion is a very brief overview of how USB works and the USB protocol. We strongly recommend that interested readers study more complete resources, particularly if attempting to write USB communication firmware. Some useful website include:

  • http://www.usb.org.- USB Implementers Forum, main USB standard source.
  • http://www.lvr.com/usb.htm. Useful information for hardware and software USB development.
  • http://www.usbmadesimple.co.uk.- A series of articles about USB

USB In Hardware

A hardware USB bus contains the following components:

  • Host Controller;
  • Root Hub;
  • Peripheral Hubs;
  • Peripheral Devices.

The host controller formats data for transmitting on the bus and translates received data to a format that operating-system components can understand. The host controller also performs other functions related to managing communications on the bus.

The root hub has one or more connectors for attaching devices. The root hub, in combination with the host controller, detects attached and removed devices, carries out requests from the host controller, and passes data between devices and the host controller.

The devices are the peripherals and additional hubs that connect to the bus. A hub has one or more ports for connecting devices. Each device must contain circuits and code that know how to communicate with the host.

USB On-The-Go (OTG) controllers contain the USB device controller and a limited capability host controller. It can be either device or host at any given time.

Currently there are three kinds of USB controllers and devices exist (as described in the current USB 2.0 Draft):

  • Low speed – its speed is up to 1,5 Megabits per second;
  • Full speed – up to 12 Megabits per second;
  • High speed – up to 480 Megabits per second.

It is permitted to attach lower speed devices to higher speed hubs. Normally higher speed devices are able to work on the lower speeds but it is not a protocol requirement.

USB devices can either be built-in into a controller USB peripheral block or can be a separate device from the controller. The former is very flexible and can be programmed to perform different functions depending on firmware whilst the latter usually have very simple interface and are limited to performing only predefined functions.

The USB Protocol

There are three layers of the protocol exist.

  • Packet layer
  • Transaction layer
  • Transfer layer

Packet Layer

On the packet layer the hub and devices exchange information by packets and these packets can contain either data or service information.

Transaction Layer

Transactions can be of the three types:

  • OUT transaction – when data is send from the hub to the device. It contains the "OUT" service packet (token), data packet from the host to device and optional acknowledge packet from the device to the host (Bulk OUT transactions);
  • IN transaction – data is send from the device to the host. It contains the "IN" token, data packet sent from the device to the host, and optional acknowledge packet sent from the host to the device (Bulk IN transactions);
  • SETUP transaction – the beginning of the control transfer, it is the host-to-device transaction and contain 8 bytes (the SETUP packet).

Transactions are addressed to the "endpoints" – elementary address part of the USB devices. There are up to 32 endpoints possible – 16 IN and 16 OUT. Endpoint 0 (IN and OUT) is the default control endpoint. It must be implemented in every device.

Transfer Layer

Bulk Transfers contain one or more Bulk IN or OUT transactions.

Asynchronous Transfers contain one or more Asynchronous IN or OUT transactions.

Control Transfers consist of the following parts:

  • SETUP stage - SETUP transaction;
  • DATA stage - Bulk IN or OUT transactions in the direction specified in the SETUP packet. It is possible to omit this stage if there is no need to send any data;
  • STATUS stage – Bulk OUT or IN transaction in the direction opposite to specified in the SETUP stage. The purpose of this stage is simply to determine whether the DATA stage was successful or not.

Before normal device operation can commence it is required to perform a special named enumeration. During this process the host controller performs device reset, reads device descriptor (to get the Endpoint 0 size) and sets the device address.

A fourth level ( or the class level) of the USB protocol determines the standard protocol for the certain device classes such as mass storage devices, communication devices etc.


INSTALLING THE USB DRIVERS

In order to run a USB simulation with Proteus you must first install the Labcenter USB Drivers. These are necessary to enable communication between the schematic and the Windows USB Drivers.

At the time of writing the USB Drivers do not support 64-Bit Operating Systems. We recommend that you install the drivers on a virtual machine (VMWare , XP Mode on Windows 7) to protect your development environment.

To install the Labcenter USB drivers

  1. Go to the Proteus 8 Professional program group on the Windows Start Menu
  2. From the ‘Virtual USB’ Menu Option select the Install USB Drivers command.

The USB Drivers will be installed in the \Windows\System32\ directory so you must have write privileges to this directory.

You can un-install the drivers at any time via the ‘Uninstall USB Drivers’ command from the Windows Start Menu.

While Labcenter have thoroughly tested these drivers and will make every effort to provide support if required we cannot make any guarantee that the installation of the drivers will not impair computer operation or the operation of any USB peripherals.


PROTEUS VSM USB SIMULATION

The main aim of the Proteus VSM USB Simulation is to allow complete simulation of those microcontrollers having an on-board USB peripheral. Since the vast majority of such devices have a USB device peripheral as opposed to a USB host controller peripheral Proteus VSM is currently limited to simulation of USB devices (devices that attach to the USB socket on the computer), and specifically to simulation of the following USB Device classes:

  • Mass Storage Devices.
  • Human Interface Devices.

Support for additional classes (and indeed additional microcontroller variants) is under consideration and, depending on demand, implementation of USB host simulation support may also be considered.

This means that the user can execute USB-related microcontroller operations in firmware, information regarding the execution of these operations will be displayed in the USB Transaction Analyser, and the communications will take place with the PC Operating System in the same way as plugging in a physical equivalent device.

The following are examples of the type of design that could be simulated using Proteus VSM:

Mass Storage Device Example

You could draw a schematic representing a USB Storage Pen and write (or modify existing) Mass Storage Device firmware. Running a simulation and closing the USB connector schematic part would then be equivalent to plugging in a physical USB pen to a USB port on your computer. Windows would detect new hardware, think for a while, and then Windows Explorer would show a new removable drive. Placing a file in the removable drive via Windows Explorer would actually write the contents of the file to the storage device (MMC Card, Memory, etc.) on the schematic.

Human Interface Device Example

You could draw a schematic representing a simple mouse pointing device and write (or modify existing) Human Interface Device Firmware. Running a simulation and closing the USB connector schematic part would then be equivalent to plugging in the USB mouse to a USB port on the computer. The firmware would control the mouse behaviour on the PC.

Fully working examples for the Mass Storage Device Class and the Human Interface Device Class can be found in the ‘..\Samples\USB\’ directory of your Proteus installation. Please read the section on Installation and Drivers before running these samples.


RUNNING A USB SIMULATION

In practise, running a USB simulation differs little from any other VSM simulation. The typical procedure is outlined below:

To run a USB simulation

  1. Set up a Virtual Machine (VMWare, Windows 7 XP Mode) and Install the USB Drivers.
  2. Design the schematic for the USB peripheral device, using one of the supported USB microcontroller models. Remember to place and wire the USBCONN USB connector part on the schematic.
  3. Take the firmware framework. for the USB device class you are implementing and modify the ‘top level’ to be application specific.
  4. Apply the COF/HEX file to the program property of the PIC18 microcontroller in the proteus schematic.
  5. Run the simulation via the PLAY button on the Animation Control Panel.
  6. Click on the USBCONN schematic part to connect the USB device – this is equivalent to plugging in the physical equivalent.
  7. If you have a licence for the USB Analyser you can use the analyser to monitor USB traffic as your simulation progresses.
  8. Debug and test as per any normal simulation – bearing in mind the timout limitations of the USB protocol.
  9. Stop the simulation via the STOP button on the Animation Control Panel when you are finished.

USB simulation can impose a significant load on CPU performance. It is most often useful to drop the processor clock frequency of the microcontroller (via the Edit Component dialogue on the schematic part) to reduce system resources. Since everything in a Proteus simulation is synchronised there is very little downside to doing this (you may also have to drop the baud rate on a UART receiver for example) but it can make significant improvement to simulation performance.

Remember that you can also monitor USB register access operations via the USB Analyser by turning on diagnostics for USB via the Configure Diagnostics dialogue on the Debug Menu in Proteus whilst the simulation is stopped.

If you do need to change the low level USB code we recommend you set up a virtual machine (or another PC) as a testing environment – see writing your own firmware for more information.

We recommend you have a look at the pre-supplied sample designs, which can be found in the ‘

'...Samples/USB/’directory of the Proteus installation. Having installed the drivers you can work through steps 4 onwards in the above listing – the USB Analyser will work without a licence for these designs.


Using the USB Transaction Analyser

THE USB TRANSACTION ANALYSER

Proteus USB Transaction Analyser During Simulation

The Proteus USB Analyser is a seperately licenced product that displays all requests and replies to and from the simulated USB device. The main Analyser window consists of two parts: the Requests List and the Requests Description.

Requests List

The requests list displays all requests in the tree form. There are three levels of the requests displaying:

  • The IRP list of requests displays type of requests (IOCTL and MJ_PNP) along with function description.
  • The Transaction list display the transaction type (IN, OUT, SETUP).
  • The Registers Operations list displays microcontroller specific registers access (reading and writing).

The LED on the left of the request list elements displays the status of the request:

  • Green – The request successfully completed;
  • Yellow – The request currently is in the execution state. The corresponding IRP request is in the pending state;
  • Red – The request failed.
  • Blue (only for transactions lists) – The transaction is completed with NAK result.

Requests Description

The Request Description forms the right hand side of the Analyser and provides detailed tabular information on the currently selected item in the Requests List. Given that the Request List is granular to three levels (as discussed above) it follows that comprehensive information can be retrieved at either the IRP Level, the Transaction Level or the Register Level

With this much information available running the USB Transaction Analyser can impose a noticeable overhead on simulation performance and can also lead to ‘information overload’. Proteus allows you to control both the level and timing of the analyser reporting in the following ways.

The small toolbar at the top of the Analyser provides options to start logging, stop logging and also to clear the log. This is particularly useful where you are interested in communications after the setup phase or in response to activity from the host controller.

Register level logging is disabled by default but can be enabled from the Configure Diagnostics command on the Debug Menu in ISIS (when the simulation is stopped). This reduces the load on simulation during normal use but allows you to enable more comprehensive logging when detailed analysis of traffic is required.


VirtualPC_Win7

Working with XP Mode on Windows 7

Overview

When creating USB devices it is important to realise that you are working at a very low level with the operating system and errors or timing failing will typically knock over the kernel resulting in a blue screen failure. To protect your working environment it is highly recommended that you set up the simulation inside a virtual machine. This section details the installation and configuration procedures for the Windows XP virtual environment provided with Windows 7.

Setting up XP Mode

For Windows XP mode on Windows 7 it is required to install first Windows Virtual PC. Open “Control Panel”, choose “Programs and Features”, and click on “Turn Windows features on or off”. Scroll to the end of the list of Windows features, and select “Windows Virtual PC”. Click OK, and it should install everything automatically.

Download the Windows XP Mode image from Microsoft website. Please make sure you’ve selected correct language: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=fb633e9d-ddbc-4044-bb09-4f99e757064e

Install using default settings and launch.

Driver Installation

Start by downloading the drivers as a separate install from the downloads page of the labcenter website (www.labcenter.com). Deposit the file in a convenient place on your hard drive. Next, open Windows Explorer inside of the Windows XP Mode machine, locate the directory with VSM_USB_installer, start it an install using default settings:

IP Address Configuration

Open the “Command Prompt” window inside of the virtual machine (start - run - cmd.exe), and enter “ipconfig” command. It should display its IP address.

It is better to switch to bridged mode here as in the default NAT mode all incoming connections are blocked. To do this, open the Tools menu at the top of the Windows XP mode machine and choose Settings. Select Networking in the settings list and change Adapter1 to be connected to your physical network card.

You may need to type “ipconfig /release” followed by “ipconfig /renew” commands after this in order to get a new IP address.

The settings here may be different depending on network configuration and corporate policies.

Firewall Configuration

Now we need to disable the firewall on the virtual machine as it will interfere in the communication process. Open “Control Panel” on the virtual machine, select Security Center, and choose “Windows Firewall” in the “Manage security settings for:” section. Turn it off and submit changes with OK button:

We also need to turn off virtual network firewall for the host computer. Open “Control Panel” on your main computer, choose “Advanced Settings”, and select “Windows Firewall Properties”. Choose “Domain Profile” tab (this might be under a a different tab in a different cases), and select “Allow” in “Inbound Connections:” field.

Schematic Configuration

The final step is to put the IP address of the virtual machine into the schematic microcontroller part. Do this by editing the part on the schematic (for example, open the Mass storage USB sample design) and specify the IP address as the USB Host Computer Address.

Submit changes with OK button, close command prompt window in the virtual machine, and run simulation in ISIS. It may issue a host computer firewall warning regarding ISIS internet connection. Allow it to work in all of the network types:

You will need to restart the simulation in ISIS if this happens as it tries to connect to the Virtual USB drivers on the virtual machine.

In the mass storage example once you start the simulation you should see that new transactions in the USB Analyser will quickly appear while the virtual operating system (inside VMWARE) will find new hardware, install drivers and the new mass storage device will appear.


VMWARE Config

Working with VMWARE

Overview

When creating USB devices it is important to realise that you are working at a very low level with the operating system and errors or timing failing will typically knock over the kernel resulting in a blue screen failure. To protect your working environment it is highly recommended that you set up the simulation inside a virtual machine. This section details the installation and configuration procedures for the popular VMWare virtual environment.

Installing VMWARE Player

Download the VMWare Player from http://www.vmware.com website Products - VMWare Player).During install, follow the default settings (clicking Next button) and then restart your system.

Setup a Virtual Machine

Start VMWare player, click on Create a New Virtual Machine and the insert your Windows XP installation disk into the DVD Drive of your PC.

Enter the Windows XP product key and leave user password empty, or enter password and select 'Log on automatically' to let the virtual machine boot automatically. Alternatively, leave the Windows product key field empty to install 31-days trial version or to enter key later:

Installing Virtual USB Drivers

Now that we have our virtual machine we need to install the USB drivers. You can download these as a separate install from the downloads page of the labcenter website (www.labcenter.com). Deposit the file on your hard drive and then drag with the left mouse button and drop it into the virtual machine. When you are hovering the mouse over the virtual machine window the cursor should change to the arrow with a plus sign in it, which means the files will be copied there.

Next, run the driver installer on the virtual machine and follow through the default installation options. You should see something like the following on completion.

Firewall Configuration

We've completed the necessary setup of the virtual machine but now need to enable communications between the virtual machine and the host computer where Proteus will be running. To do this we need to disable the firewall on the virtual machine.

Open “Control Panel” on the virtual machine, select Security Center, and choose “Windows Firewall” in the “Manage security settings for:” section. Turn it off and submit changes with OK button:

We also need to turn off virtual network firewall on the host computer. Open “Control Panel” on your main computer, choose “Advanced Settings”, and select “Windows Firewall Properties”. Choose “Public Profile” tab, click on “Customize..” button in the “Protected network connection:” section, and uncheck the “VMWare Network Adapter VMnet1” connection.

IP Address

The last thing you need to do is get the IP address of the Virtual Machine in order that we can tell the Proteus simulation which computer it needs to talk to. Open the command prompt in the virtual machine (start - run - cmd.exe) and type in 'ipconfig'. This will display the IP address.

Now open your USB design in Proteus on your main computer (e.g. the mass storage sample design) and launch the edit component dialogue form for the microcontroller. Add the virtual machines IP address to the USB Host Computer Address Field.

That completes the setup. Close the command prompt on the virtual machine and run the simulation in ISIS. You may see a host computer firewall warning regarding ISIS internet connection - if so, allow it to work in all of the network types.

You will need to restart the simulation in ISIS if this happens as it tries to connect to the Virtual USB drivers on the virtual machine.

In the mass storage example once you start the simulation you should see that new transactions in the USB Analyser will quickly appear while the virtual operating system (inside VMWARE) will find new hardware, install drivers and the new mass storage device will appear.


Writing USB Firmware

WRITING THE USB FIRMWARE

Given that many USB Frameworks are available online and that a large number of them are free and open source, it is unlikely that users will write low level USB firmware themselves.

In particular, Microchip Technologies™ provide free frameworks and working examples for use with their PIC18 FS USB microcontrollers. This code can be downloaded and adapted from http://www.microchip.com.

However, if it is necessary to start from scratch you will need a lot of knowledge of the USB protocol, instrumentation to monitor communications and a safe ‘sandpit’ to experiment in. Whilst we cannot help with the first of these our software provides unique assistance with the other pre-requisites.

The USB Transaction Analyser decodes and displays all IRP requests, USB transactions and USB related register access operations to/from the microcontroller. This is absolutely invaluable in determining when, what and where in your firmware things are going wrong.

Communicating with Windows Device Drivers is not a trivial task and can be extremely unforgiving if you get it wrong (we’ve all seen the occasional ‘Blue Screen of Death’ from Windows). Proteus USB Simulation provides a unique and extremely powerful solution to this by allowing you to route your USB communications across a network. Specifically, you can interact with a copy of Windows on a Virtual Machine (VMWare, VirtualPC, etc.). This would basically work as follows:

  1. Schematic is created on the copy of Windows installed with the PC (the native copy).
  2. Labcenter USB Drivers are installed on a copy of Windows running on a Virtual Machine (or another PC on the network).
  3. The microprocessor component on the Proteus schematic is edited and the IP address of the destination copy of Windows is entered.
  4. When you run the simulation you interact with the device drivers on the copy of Windows at the specified IP address.

This setup means that if the worst happens during the tricky stages of development you do not get a blue screen on the copy of Windows on which you are writing the firmware / designing the schematic. The Virtual Machine or second computer can be quickly rebooted whilst you examine the USB Transaction Analyser and your firmware to figure out where things went wrong.

Full installation and configuration procedures are documented for VMWARE and Windows 7 XP mode.

Don’t forget that in addition to the above you have system level debugging at your fingertips so you can easily set breakpoints and single step your code, watching the Proteus debug windows and the USB Analyser to live debug your system.

The USB Protocol has a timeout of around 30 seconds so some thought is required when stepping code – if you wait too long Windows will decide that the device is disconnected and you will have to stop and start the simulation again to re-connect. This is a ‘feature’ of the protocol itself.

Drivers

Both Windows 2000 and Windows XP contain a number of drivers for all of the standard USB devices. However, in some cases where you are creating a custom device it is possible that you will need to write your own driver. For Microsoft Windows you should start with the Microsoft WDK (Widows Drivers Kit) where you can find a lot of samples and technical documentation regarding driver development.

Microsoft Windows as standard contains the following USB drivers:

  • Host controller drivers;
  • Hub drivers;
  • Device drivers.

Drivers communicate to the Windows core and to each other using IRPs (Interrupt Request Packets). The Labcenter drivers are present the virtual Hub, which sends parts of the information contained in the IRPs to our simulation and generates answers according to responses from the simulation.

Our software is interested in two types of packets:

  • Plug-and-Play (PNP) IRPs – packets which Windows sends to the hub driver before loading of the device driver and when it is needed to perform special operations (driver unloading, etc.)
  • Input/Output Control (IOCTL) IRPs – these packets contain URB (USB Request Blocks) which ones are easy to translate into the USB transfers.

The Proteus USB Analyser shows PNP and IOCTL IRP requests and answers related to the simulated devices as well as all of the information included in these requests such as descriptors and data blocks.