1. No category

Virtual Shield
User Manual
www.virtualbreadboard.com
Date
30 Oct 2012
Description
First Draft Created
VBB Version
V 4.19
28 May 2014
Renamed as Virtual Shield
Added Virtualized Shields
Updated VirtualShield firmware
Updated VirtualShield Firmware
VBB 5.01
23 July 2014
VBB 5.05
Introduction
What is real? How do you define ‘real’. If you’re talking
about what you can feel, what you can smell, what you
can taste and see, then ‘real’ is simply electrical
signals interpreted by your brain.
Morpheus, the matrix 1999
I have always been a big fan of the matrix. It came out in the same year as Virtual
Breadboard (1999) and I immediately felt a connection between the concepts in
Virtual Breadboard and the matrix.
If your not familiar with the matrix ( I suppose it’s possible ), it’s a movie about a
world where human minds have been plugged into a virtual world in such a
convincing way that those in the virtual world are not even aware that what they are
experiencing is not real.
But how could that be? How could we mistake a simulation for reality? Morpheous
explains that- real’ is simply electrical signals interpreted by your brain. So if a
machine simulated world provided the same electrical signals to your brain as what
your sensors would produce experiencing the real world then indeed you would be
unable to tell the difference. You would live in a dream-world and not be able to tell
the difference between the real or virtual world.
Keep that thought in your mind and now think about the VirtualShield. What if the
VirtualShield was able to provide the exact same electrical signals to your Arduino
(or other microcontroller) that a real shield it is virtualizing would. How would the
Arduino know the difference between the Real shield and the VirtualShield. Well it
can’t! and this means you can run the same program with a Real or VirtualShield and
your microcontroller will never know the difference.
So in this way VirtualShield is like a ‘mini matrix’ for your Arduino. The
VirtualShield works with VirtualBreadboard to create the exact same signals for a
growing number of different shields and circuits allowing you to immerse your
Arduino in its very own virtual world. This is incredibly useful for reducing the
number of shields you need to physically own to explore more projects. You can try
out more stuff, test more stuff, share more stuff. And it’s not just the Arduino, any
microcontroller using the Arduino connectivity form factor can be put into its’ own
dream-world.
See you ‘inside’
James Caska,
Creator Virtual Breadboard
Terminology
VBB
Shield
VZ
VZS
VS
Arduino
Netduino
Propeller ASC
Amicus
ChipKit Uno32
Virtual Breadboard embedded development software platform
A daughterboard with the Arduino form-factor/footprint/pinout
VirtualiZed
VirtualiZed Shield
Virtual Shield – the physical shield that virtualizes different VZ
digital models of Shields
Arduino Form Factor development board with AVR
microcontrollers with Arduino IDE development
Arduino Form-Factor development board with .net micro
runtime
Arduino Form Factor development board for parallax propeller
Arduino Form Factor development board for microchip PIC18
with pbasic compile
Arduino Form Factor development board for Microchip PIC32
devices
Identifying Hardware Revisions
There have been 2 versions of VirtualShield manufactured at the time of writing. Both
have the ICEShield naming. Since manufacturing the ICEShield name has been
changed to VirtualShield to clarify the product functionality. Both versions use the
same firmware update from Virtual Breadboard.
Name
Maker
Power L.E.D
Color
POT’s
Processor
Revision
Errata
WaveRaster ICEShield
www.waveraster.com
Yes
Green
2
V18-26K22
MISO/MOSI swapped
When using SPI you are limited to
write only VZ Shields and you
must put a link pins 11 and 12
VBB ICEShield
www.virtualbreadboard.com
No
Blue
3
V18-26K22
MISO/MOSI swapped
When using SPI you are limited to
write only VZ Shields and you must
put a link pins 11 and 12
Working with VirtualShield
What is a Shield?
Shields are boards that can be plugged on top of the Arduino PCB extending its
capabilities. A shield has the Arduino form-factor or Pin-Out and can be stacked
ontop of each other to add even more functionality.
Why VirtualShield?
VirtualShield is the ultimate Shield library. To have the same amount of flexibility at
your fingertips you would have to own hundreds of physical shields costing thousands
of dollars
There are a multitude of ways to work with the VirtualShield
VirtualiZed Shields ( All levels )
Visual Programmable Controller ( All levels )
In-Circuit Arduino Emulator
I/O Source
I/O Monitor
Custom Circuit I/O ( Intermediate )
Standalone Operation as Output from VBB
Synchronized Virtual Circuits ( Advanced )
Hybrid Circuits
VirtualiZed Shields
.... look, see those birds? At some point a program
was written to govern them. A program was written to
watch over the trees and the wind, sunrise and
sunset. There are programs running all over the place.
The ‘Oracle’, matrix reloaded 2003
If the VirtualShield is the physical matrix, then the VirtualiZed Shields ( VZ Shields )
are the programs the matrix runs. You could say each VZ Shields are digital versions
of real shields.
A VZ Shield reconfigures the VirtualShield to behave electrically like specific real
shield so when the Arduino interacts with the VirtualShield it can’t tell the difference.
VirtualiZed Shield Mode
VirtualiZed Shields are plug and play shields that add functionality to your physical
project
1)
2)
3)
4)
5)
6)
7)
Connect the VirtualShield to USB mini and Host Arduino board
Create a new VBB project
Place a VirtualShield in VBB
Update the VirtualShield firmware ( optional and once only )
Place a VZ Shield ontop of the VirtualShield
Run VirtualBreadboard circuit
Upload your Arduino Application
Connect the VirtualShield to USB mini and Host Arduino board
The VirtualShield connects to the PC using the USB mini connector. There are no
USB drivers to install because the VirtualShield uses HID USB for which there are
already drivers available on all PC implementations.
Also install the VirtualShield on the stackable header pins on your Arduino
Compatible Host Board. The pins can only fit one way.
USB
Connection
H I D
Create a new VBB project and place a virtual shield
Create a new VBB project by starting VBB and double clicking the New Icon
Place a Virtual Shield Component
Place a Virtual Shield by clicking on the VirtualShield icon in the Toolbox and
placing on the default breadboard. The VBB VirtualShield component creates a link
with the real VirtualShield via the USB connection. VBB autodetects the
VirtualShield so you don’t need to select or configure anything.
Update the VirtualShield firmware
If this is first time you are using a new version of VBB or VirtualShield you should
update the firmware of the VirtualShield. You only need to do this once for each new
release of that has new firmware. VBB 5.01 is the latest version.
To update the firmware select the Update Virtual Shield menu item from the Help
Menu
This will launch the firmware updater and you will see progress bar appear while the
firmware is updated.
A progress bar with appear showing the progress of the firmware update. When its
finished you will see a dialog box appear with a success message.
Place a VZ Shield ontop of the VirtualShield
Select the VZ Shield you want to use from the list of VZ Shield in the VBB
VirtualiZed Shields component group.
By placing the VZ Shield ontop of the VirtualShield , VBB will automatically
configure the VirtualShield to behave like the VZ Shield. In this case a LiquidCrystal
Display
Run VirtualBreadboard circuit
Click the VBB Run button to start the Virtual Circuit and activate the VZ Shield.
VBB will start communicating with the VirtualShield and configure it to behave
electrically as a Liquid Crystal display of the same pin configuration as shown by the
digital VZ shield.
Upload your Arduino Application
So now the Arduino think it’s connected to a Liquid Crystal display (or other VZ
Shield ) and you can upload your Arduino application that start learning, testing,
developing as you would if it was a real Liquid Crystal display. Of course like any
real shield you have to take care to have the correct pin connections and drivers in
your Arduino software.
Using VZ Shields is the easiest way to work with VirtualShield and VBB. It’s quick,
plug and play and performs a specific well know task.
VZ Shield Library
Current VZ Shields
VZ LIQUID CRYSTAL
VZ DOTMATRIX
VZ 7SEG
VZ TFT
VZ LIQUID CRYSTAL
Virtualized 2 Line HD44780 Liquid Crystal Display
HD44780 Datasheet.
Features Currently Not Support
• Custom Graphics
• Visible Cursor
• Display on/off
Properties
Display Cols
8 | 10 | 16 | 20 | 32 | 40
Pins
6
9
5
4
3
2
RS
EN
DB6
DB7
DB5
DB4
Register Select
Chip Enable
Data Bit
Data Bit
Data Bit
Data Bit
NOTE: R/W is not used.. is always write.
Equivalent Circuit
Distinct VZ Shields
There are 5 distinct VZ_LCD shields possible based on the number of display
columns selected
Columns
8
10
16
20
1 Digit
32
40
Drivers
Arduino:
Arduino Standard LiquidCrystal Library:
Initialisation Code:
LiquidCrystal lcd(6, 9, 4, 5, 3, 2);
VZ DOTMATRIX
Virtualized a MAX7219 driven 8x8 Dotmatrix display with 1 to 4 digits.
Features Not Support as at v5.01
• Intensity
Properties
Color
Digits
RED | GREEN | BLUE | YELLOW
1 to 4
Pins
7
11
12
13
CS
MISO
MOSI
CLK
Chip Select. Active Low
Link to Pin 12 – see errata for your board
SPI Input Pin. VZ_DOTMATRIX is a slave board
SPI Clock
Equivalent Circuit
There are Digits MAX7219 display drivers daisy chained to drive Digits 8x8
DotMatrix L.E.D’s
Distinct VZ Shields
There are 16 distinct shields possible
1 Digit
2 Digit
3 Digit
4 Digit
RED
GREEN
BLUE
YELLOW
Drivers
Arduino
Works with Arduino Uno libraries that use either shiftout command or the SPI library.
When the SPI library is used it must be run at a slower speed by setting the clock
divider to SPI_CLOCK_DIV64.
SPI.begin();
SPI.setClockDivider(SPI_CLOCK_DIV64);
Note: Make sure you are using CS = 7
#define cs 7 // VBB Virtual Shield SPI CS
VZ 7SEG
Virtualized a MAX7219 driven series of 7 Segment display.
Features Not Support as at v5.01
• Intensity
Properties
Color
Digits
RED | GREEN | BLUE | YELLOW
1 to 4
Pins
7
11
12
13
CS
MISO
MOSI
CLK
Equivalent Circuit
Chip Select. Active Low
Link to Pin 12 – see errata for your board
SPI Input Pin. VZ_DOTMATRIX is a slave board
SPI Clock
There are Digits MAX7219 display drivers daisy chained to drive Digits 7
Segment L.E.D
Distinct VZ Shields
There are 16 distinct shields possible
1 Digit
2 Digit
3 Digit
4 Digit
RED
GREEN
BLUE
YELLOW
Drivers
Arduino
Works with Arduino Uno libraries that use either shiftout command or the SPI library.
When the SPI library is used it must be run at a slower speed by setting the clock
divider to SPI_CLOCK_DIV64.
SPI.begin();
SPI.setClockDivider(SPI_CLOCK_DIV64);
Note: Make sure you are using CS = 7
#define cs 7 // VBB Virtual Shield SPI CS
VZ TFT
Virtualized TFT 160x128 graphic LCD.
Features Not Support as at v5.01
• SD Card not available on Shield
Properties
None
Pins
7
11
12
13
CS
MISO
MOSI
CLK
Equivalent Circuit
Distinct VZ Shields
Drivers
Chip Select. Active Low
Link to Pin 12 – see errata for your board
SPI Input Pin. VZ_DOTMATRIX is a slave board
SPI Clock
Arduino
Works with Arduino TFT libraries that use SPI library
When the SPI library is used it must be run at a slower speed by setting the clock
divider to SPI_CLOCK_DIV64. Immediately after then TFTscreen.begin() call
TFTscreen.begin();
SPI.setClockDivider(SPI_CLOCK_DIV64);
Note: Make sure you are using CS = 7
#define cs 7 // VBB Virtual Shield SPI CS
Visual Programmable Controller
In addition to being able place VZ Shields onto the VirtualShield you can also place a
VirtualShield onto a Piping Board. This allows the Piping Visual Graphical Language
to interact with the real world through your VirtualShield.
TODO:
In-Circuit Emulator
TODO:
Programmable Controller
TODO:
I/O Pass-Thru
TODO:
A VirtualaliZed Shield
TODO:
In addition to the standard and synchronised IO VirtualShield supports virtual
peripheral objects. This allows faster performance than synchronised bit-banging.
The way it works is when a VBB component with a supported peripheral is wired up
to the virtual VirtualShield and the circuit is run a matching remote peripheral object
is installed.
Analog Output
The VirtualShield has Digital Potentiometers which allow for the generation of
Analog levels on the A0,A1,A2,A3 and VRef pins. When you connect an Analog
generating virtual device such as a digital potentiometer to the Virtual VirtualShield
these pins become configured as analog output.
BarGraph Example
For example, the VirtualShield in this example has an UNO as its avatar. The Slide
POT is connected to pin A0 this configured the REAL VirtualShield to use the digital
potentiometer
Virtual
Virtual
Analog
Virtual
LEDS
Real
VirtualShiel
d
VirtualShiel
d
Analog Pin
(A0)
Digital POT
VirtualShie
ld
Virtual
Analog Pin
(A0)
Analog
Real
Arduino
A0
VirtualShi
eld
Samples
Pins
Digital
Real
D2-D11
History
The VirtualShield concept came into existence to solve a growing problem for
VirtualBreadboard. When the Arduino form-factor proved a popular defacto standard
numerous microcontroller platforms emerged to enjoy the benefits of crosscompatibilty. The Arduino of course but then came the Microsoft .NET based
Netduino, the Microchip PIC32 based Uno32, the PBasic based Amicus, a Basic
Stamp version and of course our very own V18’O series.
It turns out to be impossible to simulate all and futureThat’s when the inquires started
coming in, do you support the XX-uino? At first we tried to keep up and quickly put
out versions of Netduino and also Amicus but just as quickly it became obvious it
wasn’t going to work out. Simulation is a tricky business because it can only ever
*not* be the same as the actual hardware so of course if function X from library Y of
platform Z wasn’t supported users became disappointed.
It just wasn’t really good enough to be ‘almost’ support a platform because you can
be sure the feature a user really needs for a project is the feature that’s not supported.
This has lead to a change of direction and the creation of the ICE Shield. The change
of direction is to sharpen the focus of Virtual Breadboard as a circuit emulation tool
and decouple the microcontroller platforms driving the virtual circuits with the
VirtualShield.
That is to say use REAL Microcontrollers with Virtual Breadboards using
VirtualShield as the interface.
Real
Arduino
Netduino
Uno32
xxx
VBB
Virtual
Shield
Because the VirtualShield is reading the signals and co-ordinating with VBB it
doesn’t really matter which microcontroller is on the other side. This allows VBB to
used with any Microcontroller.
There are many advantages to this approach
• Any Micro can be be used
• The preferred user toolchain can be used
• Partial circuits can be created
How it works.
There are several elements of the VirtualShield system.
Virtual ICE
Shield
VBB/
VBBExpress
VBB-RT
USB
Connection
H I D
Physical
Virtual
Shield
Host
Micro
The VirtualShield is connected to the Host Micro using the host pins
Avatars
An Avatar is a graphic of the host controller inside VBB. Even though VBB doesn’t
have a software emulation of the Micro Controller by using the Avatar and the real
Micro in conjunction with the VirtualShield it can appear to be virtual. This is a bit
like the movie Avatar where the real person drives a remote Avatar body in a different
world. The VirtualShield infrastructure becomes transparent
Uno
Avatar
Under the Hood - Advanced VirtualShield development
VirtualShield works transparently for slow moving signals or pre-made VirtualiZed
Shields but if you want to write drivers to access custome create custom circuits
Turning on a LED
Lets walk through and example to see how it works together.
Micro
13
The Host Microcontroller wants to Blink a LED on an off on Pin 13. So it will have a
program something like. I have used Arduino pseudocode – the actual code will
depend on the actual Host Microcontoller.
setup(){
pinMode( 13, OUTPUT )
}
loop(){
digitalWrite(13, HIGH);
delay(200);
digitalWrite(13, LOW);
delay(200);
}
If a real circuit you would wire a LED and a resistor to pin 13 and run the program
and the LED would flash.
If your fresh out of LEDs you can plug the VirtualShield into the HostController and
wire a virtual LED to a Virtual VirtualShield on Pin 13 , run VBB and run the Host
Micro and the LED will flash in VBB.
But how does it do that? Lets start from the VBB side.
Inside VBB, A LED is wired to pin 13 of the virtual VirtualShield.
To drive a LED requires an OUTPUT PinMode and this is how the Virtual
VirtualShield knows that the Host Micro will try to drive the LED pin. It doesn’t need
to know the program it will run it only needs to know which components are wired to
which pins and what the signals those components use. So the Virtual VirtualShield
analyses the virtual hardware wiring connections to deduce the configure the real
VirtualShield will need to interface with the real host microcontroller.
So the logic goes something like this.
•
•
•
•
•
•
•
•
Run the VBB Program
Virtual VirtualShield detects that pin 13 requires an OUTPUT Pin mode by
circuit analysis
Virtual VirtualShield sends a message to Real VirtualShield requesting Pin 13
be configured an a INPUT and to listen for changes
The real VirtualShield configures pin 13 as an INPUT and starts listening
The real Host Micro starts running its program
Pin 13 is driven high and the change is detected by the real VirtualShield
which sends a message the virtual VirtualShield notifying the change
The Virtual VirtualShield receives the message and drives the virtual Pin 13
HIGH which in turn drives the Virtual LED turning it on.
The process continues with the VirtualShield listening for changes and
notifying the virtual VirtualShield update the virtual circuit
Run VBB
Circuit
Analysis
Configure Pin 13
As INPUT
Listening
Pin 13
Run Micro
Program
Pin 13 HIGH
MSG Pin 13
digitalWrite(13, HIGH);
Changed HIGH
Pin 13 = HIGH
Pin 13 HIGH
delay(200);
MSG Pin 13
digitalWrite(13, LOW);
Changed HIGH
Pin 13 = LOW
Sim
Runtime
delay(200);
Race Conditions and Advanced interfaces
As the sequence diagram clearly shows there are unavoidable communication delays
created by sending and receiving messages. VirtualShield has been designed for lowcost so delays of several milliseconds are introduced into each step. For many human
interface signals, blinking LEDS, pressing buttons, turning relays on and off these
delays are of no concern. However for timing sensitive signals such as LCD interfaces
or logic interfaces the delays can corrupt the logic.
In addition to the basic IO there are several additional features to support more
advanced signals and thus electronic components that use them.
•
•
•
Read – The Read Pin can be configure to pulse on pin sample
Synchronize – The Synchronize pins can be configured to
Peripherals – Peripheral Objects mirror peripheral IO for high speed exchange
Conditional Compile Libraries for Host Microcontrollers
What the race conditions mean is that VirtualBreadboard hardware is *not exactly*
the same real hardware after all. Logically it is the same but race-conditions can throw
off the timing of software drivers.
When you plan to work with Virtual Hardware you may need to add conditional
compile statements to you libraries that can work with the timing features of the
VirtualShield (wait and synchronise) but then are conditionally removed when
deploying to real hardware.
Wait
The Virtual VirtualShield has Wait Read Pin property which can be set to any of the
digital pin 0 to 13. The default is none but when a pin value is set the real
VirtualShield will be configured to pulse the read pin high while it is sampling the
input pins to determine if any of the pins it is listening for have changed.
Sampling Pins
Wait
A common example is a shift register with 2 pins, a data a clock pin which increments
on the rising edge. Normally a microcontroller would just pulse the clock high and
low without worry about timing. However due to the sampling delay a software driver
needs to work with the Wait() to ensure capturing the time critical rising edge of the
CLK signal
CL
K
DAT
Shift
Register
WAIT
CL
K
WAIT
1
2
3
4
To ensure the signal is captured the drive must insert wait states that ensure the signal
is captured. For example
CLK = LOW
While( wait == LOW)
While(wait==HIGH)
CLK = HIGH
While( wait == LOW)
While(wait==HIGH)
[1] Ensures the LOW is sampled
[2]
[3] Ensures the HIGH is sampled
[4]
The Wait pin is useful for write-only operations. So writing to a LCD or a shift
register and so on.
Synch Request/Response
The Wait pin can be used for write-only circuits but when you need feedback then
you need to use the Synch pin.
A feedback circuit is where you write one or more outputs of a circuit block and then
read back the result where the result is a function of the write pins.
Write
Micro
Circuit Block
Read = F( Write )
An example of a feedback circuit is the KeyBoard scanner where the you write the
output pins of the rows and read the columns values which are function of the row
pins and the currently pressed button.
You need to use Synchronize pins to make sure the virtual function has finished
calculating and the resulting outputs are available on real pins
Virtual
Read
Virtual
Write
So the whole process goes something like this
1.
2.
3.
4.
5.
The Micro Writes to a REAL pin
VirtualShield samples the real pin and sends a message to VBB
VBB drives the value into the virtual circuit and calculates any circuit changes
The changes are sent back to the VirtualShield which writes to the real pins
The Micro reads the REAL pin
So steps 2,3,4 have a time-delay that is often nearly instantaneous when connected to
a real circuit. But how long is the delay?
You could put a long wait delay but the recommended method is to use synch
properties to configure the synch pins and use these to determine the delay
Write
Read
Virtual
Circuit with
Feedback
Synch
Request
Synch
Ready
1
2
4
3
Write(n)
Request
Ready
Read(n)
Busy
Invalid
valid
1. A change was written for which there is a feedback function to be read where
Read(n) = F( Write(n) ). When the Write is performed the values on the read
pins become invalid until F has been calculated.
2. The micro sets the Request pin high to request the circuit synchronisation
3. The VirtualShield sets the Ready Pin High to indicate the request has been
registered and is now Busy with the synchronisation process
4. The Ready pin is set to low to indicate synchronisation is complete and the
read pins are valid with the circuit function F
Remote Peripheral Objects
In addition to the standard and synchronised IO VirtualShield supports virtual
peripheral objects. This allows faster performance than synchronised bit-banging.
The way it works is when a VBB component with a supported peripheral is wired up
to the virtual VirtualShield and the circuit is run a matching remote peripheral object
is installed.
•
UART
UART
The smart UART peripheral works to enable UART communications to be passed
through to the virtual circuit at full speed.
A Virtual UART Object can be configured to take control of pins 0, 1 to pass through
serial communications.
VirtualShield currently only supports 115,200 baud in the current firmware version
So an application can run the following standard type print statement (@115Kbaud)
and when a UART component like the mini terminal is wired in VBB the message
will pass through the VirtualShield into the Virtual Circuit
public void loop(){
Serial1.println("Blink" + count++);
toggle = toggle ^ 1;
digitalWrite(13, toggle );
delay(500);
}
RX/TX Pins
When you wire up the UART RX/TX pins you need to take care. The VirtualShield
graphic and indeed the VirtualShield itself have the RX/TX pins on the opposite pins
than the host micros ( Arduino, V18’O, Netduino etc ). This is to enable the correct
RX<>TX pairing when the VirtualShield is plugged ontop of the Host micro. If you
select a Avatar then the marked RX/TX pins are the same orientation as the rest of the
circuit. If you keep the VirtualShield graphic then they will be opposite, ie from the
point of view of the VirtualShield in the real world. – See using the VirtualShield as a
Controller
Appendix
Documentation Avatars
VirtualShield
This is the default Avatar
and is a visual
representation of the
VirtualShield itself
V18’O
V18’O is
VirtualBreadboards own
Java based Microcontroller
www.virtualbreadboard.com
www.muvium.com
Uno
Uno is the popular Arduino
Uno footprint
www.arduino.cc
Uno32
Uno32 is the Microchip
PIC32 ChipKit board
http://www.chipkit.org
Netduino
Netduino is the popular
Microsoft .NET board
www.netduino.com
Working with 3V3 Host Boards
By default the VirtualShield runs at 5V and is powered by the USB. This allows the
VirtualShield to operate in standalone mode with VBB executing the application
code. However the VirtualShield has 3 solder bridges SLD1, SLD2 and SLD3 which
allow you to reconfigure the board in 3 different ways
SLD1
SLD3
SLD2
There are 3 configurations possible which allow you to operate the VirtualShield at
different voltages and also different current limits.
Powered
By
5V USB
SLD1
SLD2
SLD3
SOLDER
OPEN
OPEN
5V HOST OPEN
SOLDER
OPEN
3V HOST OPEN
OPEN
SOLDER
Powered by 5V USB.
• Standalone Mode
• Current Limited by USB
current ~500mA
Powered by Host 5V Supply
• Requires Host
• Current Limited by Host
Power Supply
Powered by Host 3V3V Supply
• Requires Host
• Current Limited by Host
Power Supply