2. General description

pied, fruits

Fraise is organized in two types of devices:

• the pied is the master of the Fraise bus. It is connected via USB to the host computer.
  There can be only one pied connected to a Fraise bus. Its task is to transmit messages from the host to the other boards, and to ask them regularly if they have a message to send to the host.
  The host however, can have multiple pieds connected to multiple USB ports, hence forming multiple Fraise buses. For this purpose, each pied must be identified by a different ID, comprised between 0 and 255. Most of the time, only one pied is needed, and has ID 1.

• the fruits are the actual application devices, they are generally the interface between the computer and the real world. They can be reprogrammed for the needs of the final application. They communicate with the host via the Fraise bus, with the pied forwarding messages through USB. Each fruit must be identified on the Fraise bus by a dedicated ID, between 1 and 126. To be able to assign them to this ID, and to send them a new program (called firmware), we also need them to have a textual name of maximum 16 characters.

Historically, the pied was a specially dedicated board (based on a PIC18K2550, featuring a USB port). Thanks to the power and ease of programming of the Raspberry Pi Pico, the pied can now host a 'virtual' fruit, which always has ID 0. We'll call it fruit0; it works exactly the same way as the other fruits, and can simply be seen as the first board, the one which is connected to the host USB.

protocol

The Fraise protocol has 2 sides: the USB protocol rules the communication between the host and the pied. The Fraise bus protocol defines the communication between the pied and the fruits.

The Fraise bus protocol is based on a 9-bit asynchronous serial communication. If the bit 9 is set, the 8 following bit are seen as the address of the fruit that must receive the next bytes. The pieds forwards the messages from the host, setting the bit 9 at the start of the message. Additionally, it regularly sends a special messages to each fruit, to which the fruit can respond with a message that it must send to the host.

The Fraise protocol allows two types of messages:

• raw bytes messages are just a list of bytes, which must be decoded by the receiver in the correct way (so the receiver must know how the message has been coded and what it represents).
• text messages are bytes that must be considered as characters. They don't need any additional convention to be readable, but they require more CPU power and need more bytes to express the same information.

The protocol implements a simple error detection system through checksum checking. This doesn't fully guarantees that the message will be transmitted, but it reduces the risk to transmit a corrupted message, and you will be warned if the message couldn't be transmitted.

The Fraise protocol also provides a special point-to-point communication mode, used by the Fraise bootloader (the bootloader is a piece of software that is written only one time into the fruit's flash memory, and will stay unchanged thereafter). This part of the protocol allows asking the bootloader to rename the fruit and to write a new application firmware to the flash memory.

The protocol is described in detail in the source code repository: protocol.md.

patches

Inside the Pd world, each board is represented by a Pd object: the pied is represented by a [pied/pied], and each fruit by a [fruit/fruit].

These objects (in fact "abstractions", i.e Pd objects that are themselves written in Pd) need arguments:

• [pied/pied PIED_ID] where PIED_ID is generally 1. You can change the ID of a pied using its "utils" dialog (this will allow to connect several pieds to you computer, using several USB ports).
  The [pied/pied] is responsible for the connection to the USB device, using the [comport] object. It receives the messages from the [fruit/fruit] objects and transmit them to the pied board, which will forward to the fruit board. Reciprocally it will forward to the right [fruit/fruit] the messages received by the pied board from a fruit board.
  Note: the [pied/pied] also centralizes the compilation process for fruit firmwares. That means you cannot compile a firmware if you have no [pied/pied] in your patch.

  Example: [pied/pied 1] will try to connect to the pied 1, and will forward messages to and from every fruit connected to this pied.

• [fruit/fruit PIED_ID FRUIT_NAME FRUIT_ID FIRMWARE_DIRNAME] where:

  • PIED_ID is the ID of the pied to which the fruit is connected.
  • FRUIT_NAME is the name of the fruit. You can rename a fruit using its "utils" dialog, you'll just have to reboot the fruit to access its bootloader.
  • FRUIT_ID is the ID of the fruit. A fruit can be assigned to any ID between 1 and 126, using its "utils" dialog.
  • FIRMWARE_DIRNAME is the name of the directory containing the source code of the firmware, and the firmware hex-file itself if it has been successfully compiled, using the "utils" dialog.

  Example: [fruit/fruit 1 my_fruit 100 my_fruit_fw] will represent a fruit board connected to the pied of ID 1, named "my_fruit", assigned to ID 100, and its firmware being contained in the my_fruit_fw/ directory.

In addition, a few objects are provided for communicating with the fruits:

• [fruit/receive FRUIT_NAME] allows you to receive messages from the board named FRUIT_NAME.
• [fruit/decode TYPE1 TYPE2 (...)] helps interpreting the messages coming from [fruit/receive].
• [fruit/send FRUIT_NAME] is used to send messages to the fruit. The left inlet sends raw-bytes-messages and the right inlet sends text-messages.

All these objects are self-documented, so you can open their help-patch by right-clicking them and select the Help menu item.

firmware

pic / pico

PCBs