ooPIC Programmer's Guide

To access an ooPIC using the B.2.X+ firmware you need to have set the ooPIC.Snode property in your ooPIC program. The address is in the range from 1 to 7, address 0 is reserved as the "everyone answer" address for programming via the serial port. If ooPIC.Snode is not set in the program then the ooPIC can only be addressed using address 0.

SCP allows any serially connected device to interact with an ooPIC with simple serial commands.  For example; if the serial connected device needed to set the position of an RC Servo connected to the ooPIC, the device would send a series of characters, such as the following, through the serial port to the ooPIC:

\041J64M

This breaks down to:  "\, Node#, Object Address, J, Object Value, M".  Where Node# is the network address of the ooPIC, Object Address is the location of the Object in memory and Object Value is the value to send to that Object.

When the ooPIC is powered up or is reset, the primary serial port's operating mode is set so that all incoming and outgoing serial data is exchanged with any serial Objects that may be dimensioned in the ooPIC's application program.  When in this mode, the SCP module will silently monitored all incoming serial data that is received by the primary serial port for the Escape Sequences that change the primary serial port's operating mode.  When the primary serial port's operating mode is switched to Serial Control Mode, all serial data is then exchanged with the SCP module until a future Escape Sequence changes the primary serial port's operating mode back to exchanging data with the serial Objects.

Escape Sequence

Escape Sequence are modeled after ANSI 'C' Escape Sequences where the Escape character is represented by the Backwards Slash character ( \ ) and the character immediately following the Escape character is used as a control value.  When the the SCP module detects the Escape character ( \ ), the next character received (the control value) is used to set the primary serial port's operating mode.

The SCP Escape Sequence [Escape] [Node] is used to place the ooPIC into Serial Control Mode where the the control value of the Escape sequence, [Node], is a 1 digit number 0-7 which represents the ooPIC's serial network Node number.  When this Escape Sequence is encountered, the [Device-Number] is checked against the ooPIC's serial network Node number and if they match, or [Device-Number] is 0, then the ooPIC will be placed into Serial Control Mode. Upon being placed in Serial Control Mode, the primary serial port's input buffer and the 3 control registers; Memory Address, Memory Type and Sub Address are cleared.  Once in Serial Control Mode, the ooPIC's SCP Module will respond to any commands that are issued.  Serial Control Mode is exited by either issuing the Exit command "X" or an Escape Sequence where the control character is a non-numeric character.  After exiting Serial Control Mode, the ooPIC's primary serial port's operating mode is set so that all incoming and outgoing serial data is exchanged with any serial Objects that may be dimensioned in the ooPIC's application program and the SCP will return to silently monitor the incoming serial data.

Example: To place the ooPIC in and out of serial control mode,
 Send "\0".  (the ooPIC is now in Serial Control Mode)
 Send "\A".  (the ooPIC is now out of serial control mode)

The ooPIC's serial network Node number is set by the ooPIC's currently running application program.  It can be any number from 0 to 7.  When set to any number other than 0, the SCP Module can be activated by either of the two Escape Sequences; [Escape] [0] or [Escape] [Node].  Note that the SCP Module will always respond to "\0" regardless of what the serial network Node has been set to. This allows up to 7 ooPIC's to share a connection to a single serial port.  When multiple ooPICs are sharing a single serial port, the Escape Sequence: [Escape] [0] will activate all of them while [Escape] [Node] will only activate the ones that are set for that Node.

When an ooPIC's SCP Module has been activated, access to its RAM memory and program EEPROM is achieved via a set of commands which are used to specify the address and type of the memory to read and write. A single uppercase ALPHA character is used to initiate each of the commands and each command returns a lower case character to indicate when it has completed its function. Most of the commands can be issued in any order. For example the Acknowledge Commands command "V" can be issued at any time to verify a valid connection with SCP, the Request Buffer command "Q" can be issued at any time to read the current contents of the SCP's input buffer, and the Exit command "X" can be issued at any time to exit SCP.

Example: To place the ooPIC in serial control mode, issue some commands, and exit serial control mode,
 Send "\0".
 Send "V". Receive "v". (verified the SCP has a valid connection)
 Send "Q". Receive "q" (nothing in input buffer)
 Send "V". Receive "v". (verified the SCP has a valid connection)
 Send "\A". (the ooPIC is now out of serial control mode)

To verify that the ooPIC was placed in serial control mode, the Acknowledge Commands Command "V" can be issued.  When the Acknowledge Commands function is on, all commands will respond with an acknowledgment character. 

Example: To place the ooPIC in serial control mode and verify a valid connection with SCP and then exit,
 Send "\0".
 Send "V". Receive "v". (Acknowledge Commands is now on)
 Send "\A". (the ooPIC is now out of serial control mode)

To discontinue Acknowledge Commands, the Silence command "U" is used. When the Acknowledge Commands function is off, only the commands that send data back to the ooPIC will respond with an acknowledgment character.

Example: To place the ooPIC in serial control mode and verify a valid connection with SCP and then exit,
 Send "\0"
 Send "V". Receive "v". (Acknowledge Commands is now on)
 Send "U". (Acknowledge Commands is now off)
 Send "\A". (the ooPIC is now out of serial control mode)

Example: To put Hex("1D3F") into the buffer, and then verify that it was received properly by reading it back,
 Send "\0V", Receive "v"
 Send "1D3F"
 Send "Q", Receive "1D3Fq"

Note that the Query Buffer command "Q" does not need for the Acknowledge Commands Command "V" to be used prior to use because it is one of the commands that send data back to the ooPIC.

Example: Same as above, but without the Acknowledge Commands Command "V",
 Send "\01D3FQ", Receive "1D3Fq"

Also note that the Request Buffer command "Q" is a non-destructive command that can be issued repeatedly without changing the bytes in the input buffer.  The Clear Buffer command "R" is used to clear the buffer.

Example: To put "1234" into the buffer, verify that it was received properly multiple times and then clear it,
 Send "\0V", Receive "v"
 Send "1234"
 Send "Q", Receive "1234q"
 Send "Q", Receive "1234q"
 Send "R", Receive "r"
 Send "Q", Receive "q"

Note that if the buffer is empty when a command that reads its value is used, then the buffer's value will be read as 0.

Also note that ALL incoming characters are stored to the input buffer.  This includes the backspace character.  Therefore, if the buffer winds up with erroneous data in it, the backspace character will not erase the data.

Before any memory type can be accessed, a few specifications must be set.  The Store Memory and Read Memory commands rely on 3 control registers that specify how to perform the read and write functions.  These control registers are; Memory Type, Memory Address, and Sub Address. 

Memory Type

Each time memory is accessed, the Memory Type control register is examined to determine what kind of memory to access and how access it.  The Memory Type is an 8-Bit value that is used to specify a number of attributes about the memory.  To set the Memory Type, the Set Type command "H" is used.  To read the Memory Type the Read Type command "G" is used.

Example: To set the Memory Type to "64", and then read the Memory Type,
 Send "\0V", Receive "v"
 Send "64H", Receive "h"
 Send "G", Receive "64g"

There are 4 different types of memory that can be accessed with SCP.  RAM, Internal EEPROM, External, and Default Object Property.  The Default Object Property is a special type of memory access. All of the Object's Default Properties physically resides inside the RAM memory which can also be accesses, but reading and writing to the Default Object Property activates critical Object routines that are required when the Object's default property changes.  External Memory is also a special type of memory.  It uses the Local I2C port to to access the ooPIC's program EEPROM located in socket E0, the data EEPROM located in socket E1 and any other I2C device that may be connected to the Local I2C port.

The following table shows the mapping of the bits of the Memory Type value:

Bit(s)	Use	Description
7	Auto-Increment Address	0: the 16-bit Memory Address control register will auto increment each time the memory is read or written. 1: the address remains unchanged when the memory is accessed.
6	Memory Type Bit-C	0: Internal Memory is accessed. 1: The Local I2C port is used to access External Memory.
5,4	Memory Type Bit-B,A	Internal Memory 11: n/a 10: read/write Internal EEPROM 01: read/write RAM. 00: read/write Object's Default property.	Local I2C port addressing: 11: n/a 10: Uses 7-Bit addressing. 01: Uses 10-Bit addressing.  00: Uses 23-Bit addressing.
3	Reserved
2 - 0	Block Size	The number of bytes to read/write when accessing Memory This value is 0 based.  I.E. 000 reads 1 byte and 111 reads 8 bytes.

Some common Memory Type values are:

• 0: Read/Write an Object's default property.
• 16 to 23: Read/Write a block of memory from 1 to 8 bytes from RAM, Increment Memory Address to next block.
• 32 to 39: Read/Write a block of memory from 1 to 8 bytes from the Internal EEPROM, Increment Memory Address to next block.
• 64 to 71: Read/Write a block of memory from 1 to 8 bytes from the External Memory, Increment Memory Address to next block.
• 144 to 151: Read/Write a block of memory from 1 to 8 bytes from RAM, Keep Memory Address the same.
• 160 to 167: Read/Write a block of memory from 1 to 8 bytes from the Internal EEPROM, Keep Memory Address the same.
• 192 to 199: Read/Write a block of memory from 1 to 8 bytes from the External Memory, Keep Memory Address the same.

Examples of these common Memory Type are shown in latter sections.

Memory Address

Each time memory is accessed, the Memory Address control register is used to determine where the accessed memory is.  The Memory Address is a 16-Bit value that is used to specify the memory's address.  To set the memory address, the Set Address command "J" is used.  To read the value in the Memory Address, the Read Address command "I" is used.

Example: To set the memory address to "126", and then read what the Memory Address is set to,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "I", Receive "126i"

Being a 16-Bit value, the Memory Address can handle memory addresses from 0 up to 65535 which allows addressing 64k byte EEPROMs.

Example: To set the memory address to "65535", and then read what the Memory Address is set to,
 Send "\0V", Receive "v"
 Send "65535J", Receive "j"
 Send "I", Receive "65536i"

When reading a block of memory from RAM or EEPROM, the Memory Address is increased by the number of bytes read or written.  This allows a subsequent memory access to occur without needing to re-specify the next memory address.  This auto increment function can be overridden by specifying a 1 in the 7th bit of the Memory Type control register previously discussed.

Sub Address

The Sub Address has a dual purpose.  When accessing RAM, it is used for block and bit address and when accessing External Memory, it is used as an I2C device address. To set the Sub Address, the Set Sub Address command "L" is used.  To read the Sub Address the Read Sub Address command "K" is used.

Example: To set the Sub Address to "84", and then read the Sub Address,
 Send "\0V", Receive "v"
 Send "84L", Receive "l"
 Send "K", Receive "84k"

The values to use for the Sub Address are discussed in more detail in latter sections.

Note:  The following examples expect that the ooPIC program currently running has an oByte Object dimensioned first.  This creates an Object at address 126.  Also note that the address of any Object dimensioned in an ooPIC application can be found by examining its address property which can be viewed by expanding the Object Icon in the Object window.

Example: To write a value of 2 to the default property of the Object at address 126, and then read it back.
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "2N", Receive "n"
 Send "M", Receive "2m"

Accessing an Object's default property activates critical Object routines that are required when the Object's default property changes.  In the last example, writing a value of 2 to an oByte Object also set the Object's non-zero property to 1.  Writing a 0, would have cleared the non-zero property to 0.

Writing without the Acknowledge Commands command can also be done,

Example: To write a value of 2 to the default property of the Object at address 126, without any verification.
 Send "\0126J2N"

If the SCP Mode is not exited and the Memory Address and Memory Type values are not changed after being set, the default Object property may be read repeatedly by reissuing the Read Memory "M" command.

Example: To read the default property of the Object at address 126, which contains the value of 2, three times,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "M", Receive "2m"
 Send "M", Receive "2m"
 Send "M", Receive "2m"

Likewise, the value may be written repeatedly.

Example: To write 2, 3 and 4 consecutively to the default property of the Object at address 126,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "2N", Receive "n"
 Send "3N", Receive "n"
 Send "4N", Receive "n"

When accessing an Object whose default property is signed, negative numbers are indicated by a dash "-" preceding the value.

Example: To read the default property of an oChar Object whose Value property is - 25,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "M", Receive "-25m"

Likewise, negative numbers may be written.

Example: To write to the default property of an oChar Object with the value of -10,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "-10N", Receive "n"
 Send "M", Receive "-10m"

Example: To read the 2 bytes of RAM that are used by an oByte Object at address 126 when the oByte's Value property has been set to a value of 5,
 Send "\0V", Receive "v"
 Send "126J", Receive "j"
 Send "145H", Receive "h"  (145 = ( [Read 2 bytes] - 1) + ( [Memory Type 1] * 16) + [128 do not auto increment the address.] )
 Send "M", Receive "AA05m"
Note that the 8-Bit Value property of the oByte Object, which was 5, was located at address 127 and therefore the Read Memory command retrieved its value.

To write to RAM memory, the Memory Type 1 and the desired Memory Address is specified followed by the values of the memory to write which are specified in 2-character per digit Hexadecimal followed by the Store Memory command "N".

Example: To write the value of the last RAM location of Bank 0 in the ooPIC when a single oByte has been programmed in,
 Send "\0V", Receive "v"
 Send "127J", Receive "j"
 Send "144H", Receive "h"  (144 = ( [Read 1 byte] - 1) + ( [Memory Type 1] * 16) + [128 do not auto increment the address.] )
 Send "06N", Receive "n"
Note that the 8-Bit Value property of the oByte Object was located at address 127 and therefore the write command set its value to 6.  Read 2 Bytes example above is done once again, the returned value will be "AA06m".

Note:  It is critical that the values to be written are properly formatted in 2-character per digit Hexadecimal.  Not doing so will cause erroneous data to be written.

Most of the data in the ooPIC is stored at the bit level and each single byte of RAM is shared with multiple data elements.  When writing to the ooPIC's RAM memory, special care must be taken to write only the bits that are applicable to the data element being written.  To accomplish this, the Sub Address control register is used to select the bits that are being accessed.  Within the Sub Address control register are values that indicate how many bits to read, and where in the byte to read them from. 

The following table shows the mapping of the Sub Address with accessing RAM:

Bit(s)	Use	Description
7 - 6	Bank Number	One of the 4 Banks of RAM
5 - 3	Bit Shift	The number of positions to left-shift the bits to match the bit position in RAM 000 = 0 bits, 001 = 1 bit,  111 = 7 bits
2 - 0	Number of Bits	The number of bits to access. 000 = 8-Bits, 001 = 1-Bit,  111 = 7-Bit,

Some common Sub Addresses for RAM access are:

• 0: Selects all 8-Bits
• 1: Selects the lower 1-Bit
• 57: Selects the upper 1-Bit
• 4: Selects the lower 4-Bits
• 36: Selects the upper 4-Bits

Example: To write a value to only the upper 4 bit positions of the last RAM location of Bank 0 in the ooPIC when a single oByte has been programmed in, a Sub Address of 36 is used.
 Send "\0V", Receive "v"
 Send "127J", Receive "j"
 Send "144H", Receive "h"
 Send "36L", Receive "l"  36 = ( [Select 4-Bits]) + ( [Shift 4 bits] * 8)
 Send "0FN", Receive "n"
Note that the 8-Bit Value property of the oByte Object was located at address 127 and therefore the write command set its upper 4-Bits to 1.  If the Read 2 Bytes example above is done once again, the returned value will be "AAF6m".

Likewise, any bits can be read.

Example: To read and write a value to only the upper 4 bit positions of the last RAM location,
 Send "\0V", Receive "v"
 Send "127J", Receive "j"
 Send "144H", Receive "h"
 Send "0L", Receive "l"  This selects all 8-bits. (0 = ( [Select 8-Bits]) + ( [Shift 0 bits] * 8) )
 Send "00N", Receive "n"  This writes a 0 to the 8-bits.
 Send "36L", Receive "h"  This selects the upper 4-bits. (36 = ( [Select 4-Bits]) + ( [Shift 4 bits] * 8) )
 Send "0FN", Receive "n"  This writes "1111" to the 4 bits.
 Send "M", Receive "0Fn"  This reads what is in the upper 4 bits.
 Send "0L", Receive "h"  This selects all 8-bits. (0 = ( [Select 8-Bits]) + ( [Shift 0 bits] * 8) )
 Send "M", Receive "F0n"  This reads all 8-bits.

Example: To write the hex(01234567) to the first locations of of the Internal EEPROM.
 Send "\0V", Receive "v"
 Send "0J", Receive "j"
 Send "160H", Receive "h"  (163 = ( [Select 1 bytes] - 1) + ( [Memory Type 2] * 16) + [128 do not auto increment the address.] )
 Send "01N", Receive "n"

NOTE:  It is critical that the values to be written are properly formatted in 2-character per digit Hexadecimal.  Not doing so will cause erroneous data to be written.

Also NOTE that the internal EEPROM needs time to write each byte, therefor if more than one byte is sent via the "N" command, only the first byte will be written.

Finally NOTE that reading the internal EEPROM does not require bit shifting, so leave the sub-address set to 0 (0L) for this type of access.

To read from the Internal EEPROM memory, the Memory Type 2 and the desired Memory Address is specified after which the Read Memory command "M" is issued.  The returned block of memory is formatted in 2-character per digit Hexadecimal.

Example: To read the 4 bytes of Internal EEPROM at address 0 written in the example above,
 Send "\0V", Receive "v"
 Send "0J", Receive "j"
 Send "160H", Receive "h"
 Send "M", Receive "01m"

When accessing the EEPROM, its I2C address must be specified with the Sub Address. For the program EEPROM in socket E0, this address is 80.

Example: To read the first 2 bytes from the Program EEPROM at I2C address 80,
 Send "\0V", Receive "v"
 Send "S", Receive "s"  (Program is now stopped)
 Send "0J", Receive "j"
 Send "65H", Receive "h"  (65 = ( [Select 2 bytes] - 1) + ( [Memory Type 4] * 16) )
 Send "80L", Receive "l"  (80 = I2C address of EEPROM )
 Send "M", Receive "0B80m"
Note that the first byte of "0B" may be different depending on the version of the program in the EEPROM.  Also note that the Memory Type was not set to inhibit auto increment and that if the Read Memory Command is pressed again, SCP will return the next 2 bytes in EEPROM.

After accessing the I2C port, the program may be resumed with the Start Program command "T".  Note that during the last example, and Objects and Virtual Circuits continue running even when the program flow had discontinued.  If the Objects and Virtual Circuits need to be stopped when accessing the EEPROM, then the Reset and Stop command "X" needs to be used instead of the Stop Program command "S".

 Send "T", Receive "t"  (Program is now running from where it stopped. 
Note that if the Reset and Stop command was used to stop the program, the Start Program command will cause the program execution to start at the MAIN( ) sub procedure.

Writing data to the Program EEPROM requires special care.  If a section of the Program EEPROM is overwritten that the remaining parts of the executing program is expecting to remain unchanged, unexpected results can occur including system lockups that can only be recovered by performing a Removed EEPROM Reset.  Generally, if data has been written to the EEPROM, such as a new program, then the ooPIC will need to be reset so that it will reinitialize the new program.  The Reset Command "W" is used to reset the ooPIC. 

Example: To write the following program into the EEPROM,

Dim R As New oDio1 Sub Main()   R.ioline = 7   R.direction = cvoutput   Do     R = ooPIC.HZ1   Loop End Sub

 Send "\0V", Receive "v"
 Send "X", Receive "s" (The ooPIC is now reset and the program is stopped.)
 Send "0J", Receive "j"
 Send "67H", Receive "h"
 Send "80L", Receive "l"
 Send "0B802901N", Receive "s"
 Send "01098789N", Receive "s"
 Send "001D8900N", Receive "s"
 Send "0E810729N", Receive "s"
 Send "B90029BEN", Receive "s"
 Send "28CE29B0N", Receive "s"
 Send "89001481N", Receive "s"
 Send "8189001DN", Receive "s"
 Send "8100FFFFN", Receive "s"
 Send "W"
Note that no command response code was received after the Reset Command and that after the reset, the ooPIC is no longer in Serial Control Mode.

It is possible to write data into the EEPROM without resetting the ooPIC.  When doing so, care must be taken to not overwrite the program currently being executed.

Example: To start and stop the program,
 Send "\0V", Receive "v"
 Send "W"
Note that no command response code was received after the Reset Command and that after the reset, the ooPIC is no longer in Serial Control Mode.

Example: To write the following program into the EEPROM,
 Send "\0V", Receive "v"
 Send "X", Receive "s" (The ooPIC is now reset and the program is stopped.)
 Send "T", Receive "t"  (Program is now running from the MAIN( ) sub procedure.)

The Reset and Stop Command "X" is also useful for when the ooPIC needs to discontinue driving the I/O lines, because resetting the ooPIC will cause all the I/O lines to go to a HI-Z logic state and will cause all the Objects and virtual circuits to discontinue operating which in the case of hardware objects, will result in discontinuing operation of their connected hardware.

Example: To single step through the program,
 Send "\0V", Receive "v"
 Send "0J", Receive "j"
 Send "P", Receive "p"  (Turn on single step and execute one instruction)
 Send "P", Receive "p"  (execute one instruction)
 Send "P", Receive "p"  (execute one instruction)
 Send "P", Receive "p"  (execute one instruction)
 Send "P", Receive "p"  (execute one instruction)
 Send "0", Receive "o"  (Turn off single step and resume program)

Note that the Step and Paused properties are also available to the ooPIC's application program.  This gives the program the ability to stop at a preprogrammed place and then wait for SCP to instruct it to resume.

A discovery routine which outputs an XML formatted list of Objects dimensioned within the current ooPIC application program is located at address 16.

Example: To call the discovery routine,
 Send "\0V", Receive "v"
 Send "16J", Receive "j"
 Send "Y", Receive "y<XML Object DATA>

BUG: Actually, this command sequence, while it works, will not output any XML object structure. The example is still good to show how to call a subroutine though.