Part1 : Create the Switch Component in Visual Basic
	Part2 : Create a Virtual Breadboard to use the new component.
	Part3 : Code Walkthrough - It worked but what happened?

Download the Source for this Tutorial. Extern_Tutorial1.zip

Part1 : Create the Switch Component in Visual Basic

Step 1: Create a Visual Basic Application and add the VBB.OCX component from the Project->Components to the project.

Step 2: Drag and Drop an instance of the VBB.OCX onto the Project Form

Step 3: Drag and Drop two picture boxs onto the form and name them picON and picOFF and set their picture property to picON.bmp and picOFF.bmp respectively. Align the pictures in the middle of the form such that the picOFF picture hides the picON picture at design time.

Step 4: Double Click the form and cut and paste the following code into the form

Private Function getExecutableName() As String
getExecutableName = App.Path & "\" & App.EXEName & ".exe"
End Function

Private Sub Form_Load()
If VBBControl1.connectVBB(True, getExecutableName) Then

VBBControl1.beginDef
VBBControl1.ComponentName = "DIP"
VBBControl1.ComponentIsAsynchronousActive
VBBControl1.setIconImage picOFF
VBBControl1.pinCount = 1
VBBControl1.pinDefinition 1, "", VBBControl1.OutputPin, 3, 1
VBBControl1.submitDef

Else
MsgBox "Failed to connnect"
End If
End Sub

Private Sub picOFF_Click()
picOFF.Visible = False
VBBControl1.doAsynchronousChange
End Sub

Private Sub picON_Click()
picOFF.Visible = True
VBBControl1.doAsynchronousChange
End Sub

Private Sub VBBControl1_Changed()
VBBControl1.PinBoolean(1) = Not picOFF.Visible
End Sub

Private Sub VBBControl1_unload()
End
End Sub
 

Step 5: Save the Project as the default and make the default Project executable

Congratulations! You have just created your first Virtual Breadboard component.

Part2 : Create a Virtual Breadboard to use the new component.

Step 1: Start Virtual Breadboard and create a new Project

Step 2: Click the External Component wizard icon in the Toolbar, Click ADD and locate Project1.exe using the file browser dialog then click OPEN

Step 4: Click OK to add the new component to Virtual Breadboard

Step 5: Wire up the component to a LED and run the Breadboard. Click the DIP in the popup window to switch the LED on the breadboard on and off.

Part3 : Code Walkthrough - It worked but what happened?

When designing a new component there are 2 tasks

	Component Definition
	Runtime Behaviour

Component Definition

Connecting to VirtualBreadboard

The component definition is where the pinout of the component is described along with the behaviour of each of the pins as either and input or output pin. The definition also defines the way the component is expected to behave. The definition of the component should be the first thing that happens when the Component.EXE is initiated and so is placed in the Form_load event

Private Sub Form_Load()
If VBBControl1.connectVBB(True, getExecutableName) Then

VBBControl1.beginDef
VBBControl1.ComponentName = "DIP"
VBBControl1.ComponentIsAsynchronousActive
VBBControl1.setIconImage picOFF
VBBControl1.pinCount = 1
VBBControl1.pinDefinition 1, "", VBBControl1.OutputPin, 3, 1
VBBControl1.submitDef

Else
MsgBox "Failed to connnect"
End If
End Sub

The first line of code attempts to establish a connection to Virtual Breadboard.

If VBBControl1.connectVBB(True, getExecutableName) Then

There are two ways to connect to Virtual Breadboard. Designtime and Runtime. If you are developing your component in Visual Basic and you want to be able the set breakpoints and receive events from Virtual Breadboard then you need to run your Visual Basic component first with Virtual Breadboard not running. Your Visual Basic code will execute up until the connectVBB() call where it will wait until you launch Virtual Breadboard. You then should launch Virtual Breadboard and open the test project that contains the component under development. Virtual Breadboard will detect the Visual Basic component and then your Visual Basic code will continue past the connectVBB() call and allow you to debug in Visual Basic using the regular breakpoints traps watches etc. If Virtual Breadboard is not launched connectVBB()  will timeout and fall through the the "Failed to connect" message.

Private Function getExecutableName() As String
getExecutableName = App.Path & "\" & App.EXEName & ".exe"
End Function

 Is an important identifier and should be used unchanged in your projects. There are 2 distinct phases of development, development/debug and release.

When you are developing your component you should compile your project in the same directory as your development project and your EXE should use the same name as your development project. ie Visual Basic project, ../YourPath/YourVBBComponent.vbp should be compiled as ../YourPath/YourVBBComponent.exe while developing. When you release your component you should place the YourVBBComponent.exe in the Externals directory of Virtual Breadboard, ie ../Virtual Breadboard/Externals/YourVBBComponent.exe where it will be autodetected by the Externals Wizard.

Defining the component

VBBControl1.beginDef

Once the connection with Virtual Breadboard has been established the component can be defined. A component is defined in a Definition Transaction. A Definition Transaction is started with beginDef and completed with submitDef.

VBBControl1.ComponentName = "DIP"

Each component has a name which is set using the ComponentName method

VBBControl1.ComponentIsAsynchronousActive

There are different types of component behavior which determine the way Virtual Breadboard evaluates the component. The DIP component doesn't care about its inputs and only changes its outputs when a user clicks it. A component that can spontaneously change its outputs, ie change its outputs without requiring its inputs to change is known as an ACTIVE component. Virtual Breadboard has a discrete timestep which it can issue to components so they can synchronise their own timings. Components that require the Synchronous clock are either SychronousActive or SynchronousPassive. The DIP component however doesn't use the Synchronous clock instead it changes its outputs asynchronously when the user clicks the DIP image. Hence the componet is an AsynchrounousActive component. Sounds confusing but there are are only 3 types of component: AsynchrounousActive,SychronousActive  and SynchronousPassive.

VBBControl1.setIconImage picOFF

When placed onto a breadboard, the component will appear either as an autogenerated image of a chip using the pinout definition or it will be represented as a ICON on the breadboard form. The default is the autogenerated chip but it can be overridden by setting the Icon Image. For best results the IconImage height and width in pixels should be divisible by 7 which is the snapgrid size in Virtual Breadboard.

VBBControl1.pinCount = 1

The number of pins the component has is specified by the pinCount property. This should be set before the definitions of individual pins is described

VBBControl1.pinDefinition 1, "", VBBControl1.OutputPin, 3, 1
 

The description of individual pins is defined by the pinDefinition(ID ,Name ,IOType, QUAD ORDER ) method. ID is the physical pin number which is 1 as there are no other pins. The Name me is set to "" because when placed on the Breadboard the DIP doesn't name its pins. The pin is an output so IOType is set to the OutputPin constant by calling the OutputPin() property. The QUAD and ORDER control where relative to the outline of the component the pins are drawn. The default position of the component is the DOWN orientation which is how the quadrants are arranged. So QUAD = 3 and ORDER =1 orientate the PIN in the bottom left of the component. However, in this case because the iconImage is used and the iconImage is exactly one pin in width (14 pixels) the pin appears directly in the centre of the component. You could use QUAD = 6 ORDER =1 or QUAD =4 ,ORDER =1 equally.

VBBControl1.submitDef

Now the component is fully defined the definition transaction is closed by submitting the component Definition.

Runtime Behaviour

The runtime behaviour of all Virtual Breadboard components revolves around 2 main concepts

	ChangeEvent
	StepEvent

ChangeEvent

When a components pin change the ChangeEvent occurs. During the change Event, the component reads the inputs and sets its outputs. All components must implement the ChangeEvent in order to do anything. Pin Values can only be read and set during the ChangeEvent. Active components can can trigger a change event by calling the doAsynchronousChange method.

StepEvent

A Synchronous component receives a step event every synchronous period. Only Synchronous components need to implement the step event

Private Sub picOFF_Click()
picOFF.Visible = False
VBBControl1.doAsynchronousChange
End Sub

Private Sub picON_Click()
picOFF.Visible = True
VBBControl1.doAsynchronousChange
End Sub

This DIP component is an Active component and triggers the Change event whenever the user clicks the picture that looks like a DIP switch on the form. To make the switch look like it is moving position there are two pictures overlayed ontop of each other with the OFF picture ontop. When the picOFF picture is clicked, it hides itself picOFF.Visible = False so that the DIP appears to have flicked to the ON position. It also triggers a change event by calling the VBBControl1.doAsynchronousChange  method. Similarly when the picON picture is clicked it makes the OFF picture appear again and calls VBBControl1.doAsynchronousChange  to indicate generate a Change Event

Private Sub VBBControl1_Changed()
VBBControl1.PinBoolean(1) = Not picOFF.Visible
End Sub

When servicing the Change() event all outputs need to be set even if they didn't change, ie the VBBOCX pins are stateless. For this example servicing the Change() event is a matter of setting the OutputPin to the boolean value of the DIP.

Private Sub VBBControl1_unload()
End
End Sub

Last but not least, the unload event is generated when Virtual Breadboard is shutting down the breadboard. You should respond to the unload event by closing and unloading any open resources you may using in your component and then end the execution of the EXE. If this is not done you will have memory resident versions of your component which will need to be shutdown manually. Note also that in the unlikely event* of Virtual Breadboard crashing it may leave External components open also requiring manual termination.