ooPIC Programmer's Guide

The Main procedure. This is the main part of your program. It contains the primary program flow.

Sub-procedures. These provide your program with sections of code that can be executed from several different points in you program.

Objects. Objects can be thought of as self-contained multitasking mini-program that runs in the background with its own set of variables. They are the way in which all ooPIC programs interact with the hardware.

Events. Events are actions or situations recognized by an Object that cause subprocedures to get executed in response to the change in an Objects state.

Virtual Circuits. Virtual Circuits are sets of objects that manipulate each others values in the background.

When an application program is created, the function of that application will rely on being able to refer to the components of that application.  To do this, the programmer of the application gives each component a name.  These names are referred to as Identifiers.  The Identifiers are then used in the application program to refer to the components.

The following lists the components that are given Identifying names.

1. Objects

2. Variables

3. Subprocedures

4. Functions

Identifier Names

Each Identifier within an application program must have a unique name so that the application program can refer to it without ambiguity. Identifier Names can be anything so long as they follow standard naming conventions.

The following lists the rules of the standard naming convention:

1. Identifier Names must begin with a letter

2. Identifier Names cannot contain a period.

3. Identifier Names must not exceed 32 characters.

4. Identifier Names must be unique within the application. (Identifier names are case insensitive) This includes local variable and object names within subprograms and functions.

The name of the Identifier is not stored in RAM and therefore can be any length (up to 255 characters) without affecting the amount of RAM that gets allocated for the Identifier's instance.

Identifier Names are case insensitive. I.E. the names: "ThingOne" and "thingone" are recognized as the same Identifier.

In Older Basic language syntax, One would find several statements and functions whose operations deal with a particular subject and are therefore related. For example, the Peek function and the Poke statement both deal with memory. The Peek function returns the value at a specified location and the Poke statement sets a specified memory location to a specified value as seen in the following example.

V = Peek(128) 'Old way to read memory location 128 into the variable V. Poke 128,V 'Old way to write the variable V into memory location 128.

The syntax of these two procedures is completely dissimilar. In ooPIC, these two operations are combined into a single Object called "oRAM". With the oRAM Object, a specified memory location is treated as a single unit and is accessed as if it was a variable. The following example demonstrates the use of an oRAM Object created with the name "MYRAM".

V = MYRAM 'New way to read a memory location into the variable V. MYRAM = V 'New way to write the variable V into a memory location.

This code reads better, is more consistent and can be understood more quickly. This language enhancement is one of the benefits of using an Object-oriented language.

In ooPIC applications an Object is declared (or an instance of it is created) with an Object Declaration statement.

The following shows the Basic syntax for creating a Variable Object.

Dim Object As New type ‘Syntax of the Dim statement

Each Object must have a unique name specified by the programmer. The Object's name is case insensitive and is the identifier that is used by the application to refer to that Object. The same rules apply to naming Objects as are applied to all other identifiers in the ooPIC language.

In ooPIC Language syntax a Variable Object is declared (or an instance of it is created) with an Object Declaration statement.

Basic syntax	variablename As VariableObjectType
Visual-Basic Syntax	Dim variablename As New VariableObjectType
C and Java Syntax	oByte variablename = New VariableObjectType;

Notice that the Variable Object creation syntax is the same syntax used to create the instances of any other type of Object.

Each Object and variable must have a unique name specified by the programmer. the Object's name is the identifier that is used by the application to refer to that variable and in all language syntax, is case insensitive. The same rules apply to naming Variables and Variable Objects as are applied to all other identifiers in the ooPIC language.

Unlike other programming languages, ooPIC’s variables are Objects. This has advantages. The most important advantage is the presence of properties.  For instance, a word variable which is 16-bits long has a property named "Bits" which in turn has several properties for the individual bytes and even the individual bits.  Each of these has properties as well.  This goes on until the smallest parts that make up the variable are reached.  For example, using a word variable named X, one can clear the sixth through the 3rd bits in just the high order byte using the following:

X.Bits.HighByte.Bits.Bits6to3.clear

The Call command instructs the program to branch to the subprocedure. The last line of the subprocedure must be End Sub. The End Sub statement causes the program flow to go back to the next statement following the Call statement.

Each subprocedure must have a unique name specified by the programmer. The subprocedure's name is case insensitive and is the identifier that is used by the application to refer to that subprocedure. The subprocedure named "MAIN" is executed when the ooPIC is powered up or reset, but only after the initialization code has finished.

Note that all variables created inside in subprocedures can only be accessed by that subprocedures.

newvalue = Sin(oldvalue)

The ooPIC languages include system-provided or intrinsic functions, like Sin.

In addition to the intrinsic functions, the programmer can define new functions. A programmer defined function is also used to perform a calculation and return the value of its result. Generally, a programmer defined function can do anything that can be done in any other part of the program with the addition of returning to the point in the program that called it with a value.

Each programmer defined function must have a unique name specified by the programmer. The function's name is the identifier that is used by the application to refer to that function and in Basic syntax, is case insensitive.

Flow Control

Flow Control statements allow the program to change the point of execution.

The Flow Control structures that ooPIC syntax supports are:

• Goto Statement
• Call Statement

Selection Structures

Selection Structures are statements that can test conditions and then, depending on the result of that test, perform different operations. The condition is usually a comparison, but it can be any expression that evaluates to a numeric value. The evaluation interprets this value as True or False; a value of 0 is False and a value of not 0 is True. The constants cvTrue and cvFalse can be used in your code in place of 0 or 1.

The decision structures that ooPIC syntax supports are:

• If Selection Construct
• Case Selection Construct

Loop Structures

Loop structures allow you to execute one or more statements repetitively.

The loop structures that ooPIC syntax supports are:

• For Loop Construct
• Do Loop Contruct
• While Loop Construct

Although the oEvent Object is the only Object in the ooPIC language that has event capabilities, other Objects can still indirectly trigger events. Other Objects can be linked to the oEvent Object thereby giving any Object event capabilities. When you want your code to respond to an event, you first create an instance of an oEvent Object with the Dim command, write code for that event and point the oEvent Object to that code, and lastly "connect" the oEvent Object to the Object that is triggering the event.

The following example shows how a voltage change on one of the ooPIC’s I/O Lines can call an event using an oDio1 Object connected to an event Object to invoke the basic syntax code subprocedure "MYEVENT".

Visual-Basic Syntax	C and Java Syntax
Dim MyEvent As New oEvent Dim ThingA As New oDIO1 Dim Wire As New oWire Sub Main() ThingA.IOLine = 1 ThingA.Direction = cvInput Wire.Input.Link(ThingA) Wire.Output1.Link(MyEvent.Operate) End Sub Sub MyEvent_Code 'event code goes here' End Sub	oEvent MyEvent = New oEvent; oDIO1 ThingA = New oDIO1; oFanOut Wire = New oWire; Void Main(Void){ ThingA.IOLine = 1; ThingA.Direction = cvInput; Wire.Input.Link(ThingA); Wire.Output1.Link(MyEvent.Operate); } Void MyEvent_Code(Void){ //event code goes here }

After executing these lines within Sub Main, the applications program flow is idle and you could add code that is free to go and do other things. A "Link" was made when the Input of the oWire Object was linked to the oDio1 Object and the Output of the oWire Object was linked to the Operate property of the oEvent Object. Now, if the voltage on the I/O line specified by the oDio1 Object’s property changes from 0 to +5 the State property of the Object named "ThingA" will change from 0 to 1, and thusly, The subprocedure named "MyEvent_Code" will be executed. When the End Sub statement is encountered at the end of the subprocedure’s code, the program will continue where it left off previously at the time of the event.  Which, in this case, would be nothing because the main subprocedure has already ended.

Event-Driven vs. Traditional Programming

In a traditional or "procedural" application, the application itself rather than an event controls the portions of code that execute. Execution starts with the first line of the program and follows a defined path through the application, branching and calling subprocedures as needed.

In comparison with the example above, a traditional application must continuously check the state of the I/O Line in order to determine when to call the subprocedure "MYEVENT_CODE". This takes up processing time for your application and can complicate the program’s flow control.

In event-driven programs, changes in the hardware’s state can cause a subprocedure to be executed even when the program flow was not expecting to do so. Therefore, the order in which your code executes depends on which events occur, which in turn depends on what the hardware does. This is the essence of event-driven programming: your code responds when it needs to.

Because the your program’s flow control does not dictate when an event will occur, your code must make a few assumptions about the "state of the world" when it executes. Your code may trigger additional events in response to its own interaction with the hardware and so, you should try to structure you application so those possibilities are anticipated.

Note: Avoid performing too many events at once. This could cause the ooPIC program stack to overflow.

Code that starts at power up.

In ooPIC Basic Syntax, the subprocedure named "MAIN" in your program is designated as the starting point. When your application powers up or is reset, the program will start executing at the first line within this subprocedure. If you want to stop the program and wait for an event to occur, simply drop out of the "MAIN" subprocedure. Another way to stop the program is by setting the ooPIC Object’s Operate property to 0 (cvOff). This will also cause the ooPIC to shut down all events and go into a low-power mode.

Prior to the "MAIN" subprocedure executing, When the ooPIC is powered up or is reset, all of the application's Object will be created and their values initialized allowing the "MAIN" subprocedure to access them.

Ending an Event-Driven program.

An Event-Driven ooPIC application stops running when all its oEvent Objects are disconnected from their triggers and no code is executing. Because no code is running and no events will occur that will run a subprocedure, there is no way to re-start the execution of the program code.

Even when no code is running, the Objects will still operate in the background until the power is shut off. Since the Operate property can be set to 0 by another Object, or even by another computer via the I2C network, the code does not need to be running to shut down the power.