Interface Protocol Pure Data and Pinguino

In here is a detailed description of the application to make Pinguino and Pure Data talk to each other, a compressed folder can be downloaded here, and there is a Tutorial here.

The files needed to perform the communication are in this zip:

IO_PureData_Pinguino_V_1_2.zip

This entry in Pinguino’s Wiki page in this link.

                                                                                                                       

Pinguino is a Microcontroller based platform similar to Arduino. These are Open Source and have been mainly aimed at artists and creators, since they offer great possibilities of interaction with devices such as sensors, lights, motors etc., and can be programmed with great ease, opening the door to inexperienced programmers.

Pinguino uses a PIC Microcontroller, from Microchip, whereas Arduino uses Atmel Microcontrollers, but for practical terms, they are the same and do the same. The main difference is the price (Pinguino is cheaper) and the community and developments (larger in Arduino).

This post is about a communication protocol I developed to control a Pinguino board in real time with software such as Pure Data or Max/MSP (Although in this case I worked with Pure Data since my Max Licence just died) It is very much like the Firmata protocol for Arduino. As I said, the difference with Pinguino is the amount of development and size of community. This is the reason for this project to exist, to keep on developing for both platforms, following the same guidelines, hoping that different applications would be compatible with both platforms. In this way, people with knowledge of Microchip could contribute to Atmel and vice versa.

The project here uses this communication protocol and firmware to enable two way messages between Pinguino and Pure Data. It allows to control the Microcontroller from Pure Data in real time, set the Digital pins to High and Low levels, as well as read them when Inputs, use the PWM based Analogue Outputs, and read the Analogue Inputs from the ADC module included in the PIC.

The same as Firmata, this firmware is based on the MIDI message format. It is implemented as a source code that can be added to the Pinguino IDE libraries. So that the programs there can include a couple of functions that perform the communication when loaded into the Pinguino board. At this stage, the firmware only supports the Pinguino PIC32 OTG board, but it is easily modified to add the particularities of Pins and Ports of your own board!.

Once the firmware is in the PIC, you can send serial messages to it via USB CDC, using a COM port on the computer side. In Pure Data this is easily done by implementing the COMPORT object, which opens a port at a custom baud rate. In here I  had to use a CDC RS-232 EMULATION DEMO from here. 

Here, all you need to do in your code on Pinguino’s IDE is tu include the function PureData.init(), which configures your PIC to the adequate Ports and Pins’ states, as well as the ADC module. Then, in the looping part of the code you need to call function PureData.communicate(char inputData[3], char Dgtl[22], long int Anlg[8]). I have included the size of the arrays that this funcion expects. PureData.communicate will return the size of InputData, filling it with the message coming from the CDC USB (from Pure Data for example).

Dgtl and Anlg will be filled with the values of all the current Digital Pins and the values of 8 channels on the ADC module. It is 8 channels, corresponding to the PIC32 OTG board.

The messages can be sent through CDC USB with Pure Data, as done in the patches that are included in the compressed file linked at the top of the page. The simplified steps of how this patches work with Pinguino by sending messages over the COM Port (CDC) are in this tutorial. I am describing the format of such messages in the next section. Here there is also a video of the interfacing in action.

[vimeo 71163895 w=500 h=275]

Interfacing Pinguino & Pure Data from Periodismo Huitlacoche on Vimeo.

Message Format Description

The communication protocol is based on the MIDI message format. In it, 3 data bytes are defined to be sent over the COM Port. For more information on the MIDI protocol refer to:

http://www.cs.cf.ac.uk/Dave/Multimedia/node158.html

Messages to the Micro-controller (PINGUINO PIC32 OTG in this case) are formatted as follows:

First byte sent (Byte 0) =  Status (instruction) message

Second byte (Byte 1)    =   Data byte 1

Third byte (Byte 2)         =   Data byte 2

SET_DIGITAL_VALUE

The “x” in the values refers to the number of the Port (channel) we want to address. i.e. if a 90 byte is passed, the channel 0 will be addressed, which in this case. corresponds to the Port B, since the PIC here does not have a Port A.

In the same fashion, a 91  corresponds to Port C an so on, depending on available ports in this PIC. A lis of ports is provided ahead in this document.

The Byte 1 determines the number of Pin of the particular Port, while Byte 2 gives the value of the state of this Pin. Here is an example:

0x920801 – This message, in hexadecimal, will set Pin 8 inPort D to HIGH, which corresponds to D6 in the Pinguino PIC32 OTG board.

Again, it is to consider that all of these values are specific and mapped to the Ports and Pins available and implemented in the Pinguino PIC32 OTG platform.

SET_ANALOG_VALUE

The same logic as in the SET_DIGITAL_VALUE, except that in this case there are only 3 available analogue outputs in this Pinguino board (D0-D2), which means that the second half of Byte 0 will represent this number of output.

Bytes 1 and 2 are used to carry the 10 bit analogue value supported by the PWM in the PIC. Byte 2 carries the less significant byte, whereas Byte 1 does the opposite. Example:

0xE100FF – This message will set D1 (RD3) to 200

0xE203E8 – This message will set D2 (RD4) to 1000

SET_PIN_VALUE

As with the Digital Values, the second half of Byte 0 gives the number of the channel we are addressing. Here the values start from F4, following the already established protocol of similar platforms (Firmata). 1 is an input, while 0 is an Output.

0xF40201 – Sets Port B, Pin 2 to Input.

Instruction List

In this final section I am copying the entire list of instructions used for this protocol, as sent to the PIC to control it.

SET_DIGITAL_VALUE
PIC Pin	Pinguino Pin	Byte 0 (Hex)	Byte 1 (Hex)	Byte 2
RD0	BUTTON	92	0	1 or 0
RD1	LED 2	92	1	1 or 0
RD2	D0	92	2	1 or 0
RD3	D1	92	3	1 or 0
RD4	D2	92	4	1 or 0
RD5	D3	92	5	1 or 0
RD6	D4	92	6	1 or 0
RD7	D5	92	7	1 or 0
RD8	D6	92	8	1 or 0
RD11	D7	92	B	1 or 0
RB13	D8	90	D	1 or 0
RB14	D9	90	E	1 or 0
RG9	D10	95	9	1 or 0
RG8	D11	95	8	1 or 0
RG7	D12	95	7	1 or 0
RG6	D13 (LED 1)	95	6	1 or 0
RB1/AN1	A0	90	1	1 or 0
RB2/AN2	A1	90	2	1 or 0
RB3/AN3	A2	90	3	1 or 0
RB4/AN4	A3	90	4	1 or 0
RB8/AN8	A4	90	8	1 or 0
RB9/AN9	A5	90	9	1 or 0
RB11/AN11	A6	90	B	1 or 0
RB10/AN10	A7	90	A	1 or 0

SET_ANALOG_VALUE
PIC Pin	Pinguino Pin	Byte 0 (Hex)	Byte 1 (Hex)	Byte 2
RD2	D0	E0	MSByte	LSByte
RD3	D1	E1	MSByte	LSByte
RD4	D2	E2	MSByte	LSByte

SET_ANALOG_VALUE
PIC Pin	Pinguino Pin	Byte 0 (Hex)	Byte 1 (Hex)	Byte 2
RD0	BUTTON	F6	0	1 or 0
RD1	LED 2	F6	1	1 or 0
RD2	D0	F6	2	1 or 0
RD3	D1	F6	3	1 or 0
RD4	D2	F6	4	1 or 0
RD5	D3	F6	5	1 or 0
RD6	D4	F6	6	1 or 0
RD7	D5	F6	7	1 or 0
RD8	D6	F6	8	1 or 0
RD11	D7	F6	B	1 or 0
RB13	D8	F4	D	1 or 0
RB14	D9	F4	E	1 or 0
RG9	D10	F9	9	1 or 0
RG8	D11	F9	8	1 or 0
RG7	D12	F9	7	1 or 0
RG6	D13 (LED 1)	F9	6	1 or 0
RB1/AN1	A0	F4	1	1 or 0
RB2/AN2	A1	F4	2	1 or 0
RB3/AN3	A2	F4	3	1 or 0
RB4/AN4	A3	F4	4	1 or 0
RB8/AN8	A4	F4	8	1 or 0
RB9/AN9	A5	F4	9	1 or 0
RB11/AN11	A6	F4	B	1 or 0
RB10/AN10	A7	F4	A	1 or 0