MIDIbox Network (MBNet)

Defined in January 2007

The MIDIbox Network concept is the basis for linking multiple Core Modules in the upcoming MIDIbox SID V2 project, and it will replace the MIDIbox Link which was used in the previous version.

The High Level Protocol (HLP) has been prepared for communication with other MIDIbox applications over the same network. It is multimaster capable. Up to 128 network nodes are supported. 8 nodes can act as a master, and all nodes can operate as slaves.

Note that it isn't the intention to define an universal protocol for multiple purposes. The scope is on exchanging control informations and RAM buffer contents, similar to MIDI, but much faster and especially bidirectional without the need for point-to-point connections (MIDI Out->MIDI In).

Physical/Transfer Layer

For the physical/transfer layer the CAN (Controller Area Network) standard has been selected, since many inexpensive microcontrollers are available in the meantime, which include an integrated CAN controller. The PIC18F4685 is predestinated for MIOS, as it not only contains an ECAN peripheral, but also enough RAM (no compatibility issues) and more than enough flash memory (96k) for upcoming MIDIbox applications.

High Level Protocol

The HLP uses a simple request-acknowledge scheme. A master sends a message to the slave and waits for a response, before the next message is sent. There is no stack-based implementation allowed like known from TCP. The software based flow control throttles the bandwidth, but also reduces the memory and data managing requirements for the slaves. The CPU load is low compared to other bidirectional interfaces like IIC or SPI, the bitrate is higher (1 MBit/s), accordingly CAN is a good selection for performance critical applications.

The ECAN peripheral is configured in Mode 1 (Enhanced Legacy Mode) with 1 transmit buffer for sending commands, 7 receive buffers for receiving commands from different masters, and a dedicated transmit and receive buffer for handling the acknowledge messages.

CAN frames are sent in extended format with 29 bit identifier. Parts of the identifier contain control or address informations. The acceptance mask only filters the bitfield 10:3 (8 bits). 7 bits for addressing the node, and another for seperating acknowledge messages:

The 2-bit wide TOS (Type-Of-Service) field qualifies the CAN message for different purposes. Together with the A (acknowledge) flag, 8 different types are available:

A	TOS	Purpose	Control Field	Payload
0	0	Special Service	Bitfield 18:11 contains the service ID, Bitfield 26:19 is unused	depends on service, see below
0	1	Read RAM	Bitfield 26:11 contains the address (16-bit, 64k address space), the acknowledge response with TOS=1 will always contain 8 bytes, starting from the given address. Depending on the application, the RAM could be segmented into different partitions for different purposes (e.g. Patch, Ensemble, Drumkit)	unused
0	2	Write RAM	Bitfield 26:11 contains the address (16-bit, 64k address space).	1-8 bytes which will be written into RAM
0	3	Ping	unused, the acknowledge response with TOS=0 will contain 8 bytes with the Pong Response (see below)	unused
A	TOS	Purpose	Control Field	Payload
1	0	Acknowledge Response with status "Ok"	Bitfield 18:11 contains the node ID of the sender for doublechecking the flow.	no payload on normal replies. 8 bytes on a ping response ("Pong"). Structure see below.
1	1	Acknowledge Response on Read	Bitfield 18:11 contains the node ID of the sender for doublechecking the flow.	8 bytes, starting from the requested address (A=0, TOS=1)
1	2	Acknowledge Response with status "Retry"	Bitfield 18:11 contains the node ID of the sender.	Sent when a slave was not ready for handling the requested TOS, e.g. if it has been temporary locked by another master.
1	3	Acknowledge Response with status "Error"	Bitfield 18:11 contains the node ID of the sender.	Sent on an unknown or invalid message.

The Node field contains the MIOS Device ID (0-127) of the receiver, and the MS field contains bitfield 6:4 of the MIOS Device ID of the master (0, 16, 32, 48, ... 112), to which the slave will acknowledge. Accordingly, the MIOS Device ID of the master is reduced to 8 possible values. Bitfield 3:0 has to be 0!

If a slave doesn't respond within 10 miliseconds, it can be assumed that it is not connected to the network. Optionally the master can retry the transmission.

A master can detect a slave during runtime by sending a ping, waiting for the pong response, and checking the content of the payload (hot-plug).

Ping Response (Device Identifier)

The Ping Response ("Pong") contains an 8 byte identifier which allows the master to determine the compatibility of the detected slave.

Byte #	Description
0	Protocol Version - currently: 1
1-4	4 Characters which identify the Slave Type. Currently supported: "SID " (MIDIbox SID)
5	Major Version Number of the Firmware. For "SID ": 1 or 2
6-7	Subversion Number of the Firmware, 16bit value, little-endian coded (low-byte first)

The identifier not only allows a master to check, if a slave is compatible, e.g. with the control surface. It also allows to switch between different parameter and control structures. If for example a MIDIbox SID receives the identifier of a MIDIbox FM, it could automatically adapt the menu and encoder/button/LED functions to this different synthesizer.

However, the HLP is not flexible enough for exchanging meta informations about synthesizers and control surfaces. The application must be prepared for supporting new devices. New synths will always require a firmware update (and some programming effort), so long they are not a derivative of an already supported synth.

Special Service

The Special Service TOS (0) can be seen as a TOS extension with up to 256 additional commands to a slave. Command 0-15 is reserved for the HLP and MIOS, whereas Command 16-127 is application specific.

Service	Description
0	Lock receiver for the given master (MS field). The receiver will stall the main thread (interrupts still allowed) and only reply to incoming messages from the master which has requested the lock. If another master has already locked, the receiver will send a retry response. This command should be used for fast bulk dumps to ensure best transfer rates with best response times.
1	Unlock receiver. Once this message has been received, the receiver will continue the main thread. Upcoming messages could be acknowledged with higher latencies (typical 100 uS..1mS, up to 10 mS)
2, 3	reserved for HLP specific services
4	MIOS call: USER_Init - payload=0 (no parameters)
5	MIOS call: USER_MPROC_DebugTrigger - payload=4 bytes (values copied into WREG and MIOS_PARAMETER[123])
6	MIOS call: USER_MPROC_NotifyReceivedEvent - payload=3 bytes (values copied into MIOS_PARAMETER[123])
7	MIOS call: USER_MPROC_NotifyReceivedByte - payload=1 byte (value copied into WREG and MIOS_PARAMETER1)
8	MIOS call: USER_DIN_NotifyToggle - payload=2 bytes (values copied into WREG and MIOS_PARAMETER[12])
9	MIOS call: USER_ENC_NotifyChange - payload=2 bytes (values copied into WREG and MIOS_PARAMETER[12])
10	MIOS call: USER_AIN_NotifyChange - payload=3 bytes (values copied into WREG and MIOS_PARAMETER[123])
11-15	reserved for additional MIOS calls
16-127	Application specific services

MIOS calls are useful for remote-controlling a MIDIbox. Button, Pot and Encoder movements can be simulated from another MIDIbox. Note that the application has to avoid recursions by itself. It must be prevented, that a button/pot/encoder movement starts a new CAN message, which could violate the simple request/acknowledge scheme of the HLP.

Note also, that remote controlling could fail, if the application takes the controller (button/encoder/pot) value from a MIOS function, instead of the passed MIOS_PARAMETERs

The call of USER_NotifyReceivedByte could bypass the integrated MIDI merger, incoming MIDI bytes could be mixed up with incoming CAN messages and "confuse" e.g. the SysEx parser. Therefore these messages only work under special circumstances. The preferred solution for applications is to provide dedicated special commands for SysEx-like transactions, or to allow access to the internal memory via RAM read/write (TOS 1/2) transactions.

Copyright © 1998-2023, Thorsten Klose. All rights reserved.