# MIOS32_MIDI

Collaboration diagram for MIOS32_MIDI:

## Data Structures
union | sysex_state_t
union | sysex_timeout_ctr_flags_t
## Functions
s32 | MIOS32_MIDI_Init (u32 mode)
s32 | MIOS32_MIDI_CheckAvailable (mios32_midi_port_t port)
s32 | MIOS32_MIDI_RS_OptimisationSet (mios32_midi_port_t port, u8 enable)
s32 | MIOS32_MIDI_RS_OptimisationGet (mios32_midi_port_t port)
s32 | MIOS32_MIDI_RS_Reset (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendPackage_NonBlocking (mios32_midi_port_t port, mios32_midi_package_t package)
s32 | MIOS32_MIDI_SendPackage (mios32_midi_port_t port, mios32_midi_package_t package)
s32 | MIOS32_MIDI_SendEvent (mios32_midi_port_t port, u8 evnt0, u8 evnt1, u8 evnt2)
s32 | MIOS32_MIDI_SendNoteOff (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 note, u8 vel)
s32 | MIOS32_MIDI_SendNoteOn (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 note, u8 vel)
s32 | MIOS32_MIDI_SendPolyPressure (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 note, u8 val)
s32 | MIOS32_MIDI_SendCC (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 cc_number, u8 val)
s32 | MIOS32_MIDI_SendProgramChange (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 prg)
s32 | MIOS32_MIDI_SendAftertouch (mios32_midi_port_t port, mios32_midi_chn_t chn, u8 val)
s32 | MIOS32_MIDI_SendPitchBend (mios32_midi_port_t port, mios32_midi_chn_t chn, u16 val)
s32 | MIOS32_MIDI_SendSpecialEvent (mios32_midi_port_t port, u8 type, u8 evnt0, u8 evnt1, u8 evnt2)
s32 | MIOS32_MIDI_SendMTC (mios32_midi_port_t port, u8 val)
s32 | MIOS32_MIDI_SendSongPosition (mios32_midi_port_t port, u16 val)
s32 | MIOS32_MIDI_SendSongSelect (mios32_midi_port_t port, u8 val)
s32 | MIOS32_MIDI_SendTuneRequest (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendClock (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendTick (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendStart (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendContinue (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendStop (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendActiveSense (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendReset (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendSysEx (mios32_midi_port_t port, u8 *stream, u32 count)
s32 | MIOS32_MIDI_SendDebugStringHeader (mios32_midi_port_t port, char command, char first_byte)
s32 | MIOS32_MIDI_SendDebugStringBody (mios32_midi_port_t port, char *str, u32 len)
s32 | MIOS32_MIDI_SendDebugStringFooter (mios32_midi_port_t port)
s32 | MIOS32_MIDI_SendDebugString (const char *str)
s32 | MIOS32_MIDI_SendDebugMessage (const char *format,...)
s32 | MIOS32_MIDI_SendDebugHexDump (const u8 *src, u32 len)
s32 | MIOS32_MIDI_ReceivePackage (mios32_midi_port_t port, mios32_midi_package_t package, void *_callback_package)
s32 | MIOS32_MIDI_Receive_Handler (void *_callback_package)
s32 | MIOS32_MIDI_Periodic_mS (void)
s32 | MIOS32_MIDI_DirectTxCallback_Init (s32(*callback_tx)(mios32_midi_port_t port, mios32_midi_package_t package))
s32 | MIOS32_MIDI_DirectRxCallback_Init (s32(*callback_rx)(mios32_midi_port_t port, u8 midi_byte))
s32 | MIOS32_MIDI_SendByteToRxCallback (mios32_midi_port_t port, u8 midi_byte)
s32 | MIOS32_MIDI_SendPackageToRxCallback (mios32_midi_port_t port, mios32_midi_package_t midi_package)
s32 | MIOS32_MIDI_DefaultPortSet (mios32_midi_port_t port)
mios32_midi_port_t | MIOS32_MIDI_DefaultPortGet (void)
s32 | MIOS32_MIDI_DebugPortSet (mios32_midi_port_t port)
mios32_midi_port_t | MIOS32_MIDI_DebugPortGet (void)
s32 | MIOS32_MIDI_DeviceIDSet (u8 device_id)
u8 | MIOS32_MIDI_DeviceIDGet (void)
s32 | MIOS32_MIDI_SysExCallback_Init (s32(*callback_sysex)(mios32_midi_port_t port, u8 midi_in))
s32 | MIOS32_MIDI_DebugCommandCallback_Init (s32(*callback_debug_command)(mios32_midi_port_t port, char c))
s32 | MIOS32_MIDI_FilebrowserCommandCallback_Init (s32(*filebrowser_debug_command)(mios32_midi_port_t port, char c))
s32 | MIOS32_MIDI_TimeOutCallback_Init (s32(*callback_timeout)(mios32_midi_port_t port))
## Variables
const u8 | mios32_midi_pcktype_num_bytes [16]
const u8 | mios32_midi_expected_bytes_common [8]
| Number if expected bytes for a common MIDI event - 1.
const u8 | mios32_midi_expected_bytes_system [16]
| Number if expected bytes for a system MIDI event - 1.
const u8 | mios32_midi_sysex_header [5] = { 0xf0, 0x00, 0x00, 0x7e, 0x32 }
| should only be used by MIOS32 internally and by the Bootloader!
unsigned sysex_state_t::MY_SYSEX:1
unsigned sysex_state_t::CMD:1
struct {
unsigned CTR:3
unsigned sysex_state_t::MY_SYSEX:1
unsigned sysex_state_t::CMD:1
} | sysex_state_t::general
unsigned sysex_state_t::MY_SYSEX:1
unsigned sysex_state_t::CMD:1
unsigned sysex_state_t::PING_BYTE_RECEIVED
struct {
unsigned CTR:3
unsigned sysex_state_t::MY_SYSEX:1
unsigned sysex_state_t::CMD:1
unsigned sysex_state_t::PING_BYTE_RECEIVED
} | sysex_state_t::ping
unsigned long long sysex_timeout_ctr_flags_t::iic_receives:16
unsigned long long sysex_timeout_ctr_flags_t::spi_receives:16
struct {
unsigned long long usb_receives:16
unsigned long long sysex_timeout_ctr_flags_t::iic_receives:16
unsigned long long sysex_timeout_ctr_flags_t::spi_receives:16
}; |

## Detailed Description

MIDI layer functions for MIOS32

the mios32_midi_package_t format complies with USB MIDI spec (details see there) and is used for transfers between other MIDI ports as well.

## Function Documentation

s32 MIOS32_MIDI_CheckAvailable | ( | mios32_midi_port_t | port | ) |

This function checks the availability of a MIDI port

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)

Returns:
  1: port available
  0: port not available

Here is the call graph for this function:

s32 MIOS32_MIDI_DebugCommandCallback_Init | ( | s32(*)(mios32_midi_port_t port, char c) | callback_debug_command | ) |

Installs the debug command callback function which is executed on incoming characters from a MIOS Terminal

Example:

     s32 CONSOLE_Parse(mios32_midi_port_t port, char c)
     {
       // see $MIOS32_PATH/apps/examples/midi_console/

       return 0; // no error
     }

The callback function has been installed in an Init() function with:

       MIOS32_MIDI_DebugCommandCallback_Init(CONSOLE_Parse);

Parameters:

  `[in]` | callback_debug_command | the callback function (NULL disables the callback)

Returns:
  < 0 on errors

mios32_midi_port_t MIOS32_MIDI_DebugPortGet | ( | void |  | ) |

This function returns the MIDI_DEBUG port

Returns:
  the debug port

s32 MIOS32_MIDI_DebugPortSet | ( | mios32_midi_port_t | port | ) |

This function allows to change the MIDI_DEBUG port.
The preset which will be used after application reset can be set in mios32_config.h via "#define MIOS32_MIDI_DEBUG_PORT <port>".
It's set to USB0 as long as not overruled in mios32_config.h

Parameters:

  `[in]` | port | MIDI port (USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)

Returns:
  < 0 on errors

mios32_midi_port_t MIOS32_MIDI_DefaultPortGet | ( | void |  | ) |

This function returns the DEFAULT port

Returns:
  the default port

s32 MIOS32_MIDI_DefaultPortSet | ( | mios32_midi_port_t | port | ) |

This function allows to change the DEFAULT port.
The preset which will be used after application reset can be set in mios32_config.h via "#define MIOS32_MIDI_DEFAULT_PORT <port>".
It's set to USB0 as long as not overruled in mios32_config.h

Parameters:

  `[in]` | port | MIDI port (USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)

Returns:
  < 0 on errors

u8 MIOS32_MIDI_DeviceIDGet | ( | void |  | ) |

This function returns the SysEx Device ID, which is used during parsing incoming SysEx Requests to MIOS32
It can also be used by an application for additional parsing with the same ID.
The initial ID is stored inside the BSL range and will be recovered after reset. It can be changed by the user with the bootloader update tool

Returns:
  SysEx device ID (0x00..0x7f)

s32 MIOS32_MIDI_DeviceIDSet | ( | u8 | device_id | ) |

This function sets the SysEx Device ID, which is used during parsing incoming SysEx Requests to MIOS32
It can also be used by an application for additional parsing with the same ID.
ID changes will get lost after reset. It can be changed permanently by the user via the bootloader update tool

Parameters:

  `[in]` | device_id | a new (temporary) device ID (0x00..0x7f)

Returns:
  < 0 on errors

s32 MIOS32_MIDI_DirectRxCallback_Init | ( | s32(*)(mios32_midi_port_t port, u8 midi_byte) | callback_rx | ) |

Installs the Rx callback function which is executed immediately on each incoming/outgoing MIDI byte, partly from interrupt handlers.

This function should be executed so fast as possible. It can be used to trigger MIDI Rx LEDs or to trigger on MIDI clock events. In order to avoid MIDI buffer overruns, the max. recommented execution time is 100 uS!

It is possible to filter incoming MIDI bytes with the return value of the callback function.

Parameters:

  `[in]` | *callback_rx | pointer to callback function:
          s32 callback_rx(mios32_midi_port_t port, u8 midi_byte)
          {
          }
  The byte will be forwarded into the MIDI Rx queue if the function returns 0. It will be filtered out if the callback returns != 0 (e.g. 1 for "filter", or -1 for "error").

Returns:
  < 0 on errors

Note:
  Please use the filtering capabilities with special care - if a port is filtered which is also used for code upload, you won't be able to exchange the erroneous code w/o starting the bootloader in hold mode after power-on.

s32 MIOS32_MIDI_DirectTxCallback_Init | ( | s32(*)(mios32_midi_port_t port, mios32_midi_package_t package) | callback_tx | ) |

Installs the Tx callback function which is executed by MIOS32_MIDI_SendPackage_NonBlocking() before the MIDI package will be forwarded to the physical interface.

The callback allows following usecases:

- package filter
- duplicating/routing packages
- monitoring packages (sniffer)
- create virtual busses; loopbacks
- extend available ports (e.g. by an OSC or AOUT port)
  It is recommented to give port extensions a port number >= 0x80 to avoid incompatibility with future MIOS32 port extensions.

Parameters:

  `[in]` | *callback_tx | pointer to callback function:
          s32 callback_tx(mios32_midi_port_t port, mios32_midi_package_t package)
          {
          }
  The package will be forwarded to the physical interface if the function returns 0. Should return 1 to filter a package. Should return -2 to initiate a retry (function will be called again) Should return -3 to report any other error. These error codes comply with MIOS32_MIDI_SendPackage_NonBlocking()

Returns:
  < 0 on errors

Note:
  Please use the filtering capabilities with special care - if a port is filtered which is also used for code upload, you won't be able to exchange the erroneous code w/o starting the bootloader in hold mode after power-on.

s32 MIOS32_MIDI_FilebrowserCommandCallback_Init | ( | s32(*)(mios32_midi_port_t port, char c) | filebrowser_debug_command | ) |

Installs the filebrowser command callback function which is executed on incoming characters from aMIOS Filebrowser

Usage example: see terminal.c of $MIOS32_PATH/apps/controllers/midio128

The callback function has been installed in an Init() function with:

       MIOS32_MIDI_FilebrowserCommandCallback_Init(CONSOLE_Parse);

Parameters:

  `[in]` | callback_debug_command | the callback function (NULL disables the callback)

Returns:
  < 0 on errors

s32 MIOS32_MIDI_Init | ( | u32 | mode | ) |

Initializes MIDI layer

Parameters:

  `[in]` | mode | currently only mode 0 supported

Returns:
  < 0 if initialisation failed

Here is the call graph for this function:

s32 MIOS32_MIDI_Periodic_mS | ( | void |  | ) |

This function should be called periodically each mS to handle timeout and expire counters.

Not for use in an application - this function is called by by a task in the programming model!

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_Receive_Handler | ( | void * | _callback_package | ) |

Checks for incoming MIDI messages and calls callback_package function with following parameters:

        callback_package(mios32_midi_port_t port, mios32_midi_package_t midi_package)

Not for use in an application - this function is called by by a task in the programming model, callback_package is APP_MIDI_NotifyPackage()

SysEx streams can be optionally redirected to a separate callback function which can be installed via MIOS32_MIDI_SysExCallback_Init()

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_ReceivePackage | ( | mios32_midi_port_t | port,
|  | mios32_midi_package_t | package,
|  | void * | _callback_package |
| ) |  |  |

Processes a received package.

Used by MIOS32_MIDI_Receive_Handler, but could also be called from an application, e.g. for passing messages from "virtual ports" which are not handled by MIOS32_MIDI_Receive_Handler

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | package | MIDI package
  `[in]` | _callback_package | typically APP_MIDI_NotifyPackage

Returns:
  -1 if port not available
  0 on success

s32 MIOS32_MIDI_RS_OptimisationGet | ( | mios32_midi_port_t | port | ) |

This function returns the running status optimisation enable/disable flag for the given MIDI OUT port.

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)

Returns:
  -1 if port not available or if it doesn't support running status
  0 if optimisation disabled
  1 if optimisation enabled

Here is the call graph for this function:

s32 MIOS32_MIDI_RS_OptimisationSet | ( | mios32_midi_port_t | port,
|  | u8 | enable |
| ) |  |  |

This function enables/disables running status optimisation for a given MIDI OUT port to improve bandwidth if MIDI events with the same status byte are sent back-to-back.
The optimisation is currently only used for UART based port (enabled by default), IIC: TODO, USB: not required).

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7)
  `[in]` | enable | 0=optimisation disabled, 1=optimisation enabled

Returns:
  -1 if port not available or if it doesn't support running status
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_RS_Reset | ( | mios32_midi_port_t | port | ) |

This function resets the current running status, so that it will be sent again with the next MIDI Out package.

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)

Returns:
  -1 if port not available or if it doesn't support running status
  0 if optimisation disabled
  1 if optimisation enabled

Here is the call graph for this function:

s32 MIOS32_MIDI_SendActiveSense | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendAftertouch | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendByteToRxCallback | ( | mios32_midi_port_t | port,
|  | u8 | midi_byte |
| ) |  |  |

This function is used by MIOS32 internal functions to forward received MIDI bytes to the Rx Callback routine.

It shouldn't be used by applications.

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | midi_byte | received MIDI byte

Returns:
  < 0 on errors

s32 MIOS32_MIDI_SendCC | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | cc_number,
|  | u8 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendClock | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendContinue | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugHexDump | ( | const u8 * | src,
|  | u32 | len |
| ) |  |  |

Sends an hex dump (formatted representation of memory content) to the MIOS Terminal in MIOS Studio.

The MIDI port used for debugging (MIDI_DEBUG) can be declared in mios32_config.h:

       #define MIOS32_MIDI_DEBUG_PORT USB0

(USB0 is the default value)

Optionally, the port can be changed during runtime with MIOS32_MIDI_DebugPortSet

Parameters:

  `[in]` | *src | pointer to memory location which should be dumped
  `[in]` | len | number of bytes which should be sent

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugMessage | ( | const char * | format,
|  |  | ... |
| ) |  |  |

Sends a formatted Debug Message to the MIOS Terminal in MIOS Studio.

Formatting parameters are like known from printf, e.g.

       MIOS32_MIDI_SendDebugMessage("Button %d %s\n", button, value ? "depressed" : "pressed");

The MIDI port used for debugging (MIDI_DEBUG) can be declared in mios32_config.h:

       #define MIOS32_MIDI_DEBUG_PORT USB0

(USB0 is the default value)

Optionally, the port can be changed during runtime with MIOS32_MIDI_DebugPortSet

Please note that the resulting string shouldn't be longer than 128 characters!
If the *format string is already longer than 100 characters an error message will be sent to notify about the programming error.
The limit is set to save allocated stack memory! Just reduce the formated string to print out the intended message.

Parameters:

  `[in]` | *format | zero-terminated format string - 128 characters supported maximum!
  | ... | additional arguments

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugString | ( | const char * | str | ) |

Sends a string to the MIOS Terminal in MIOS Studio.

In distance to MIOS32_MIDI_SendDebugMessage this version is less costly (it doesn't consume so much stack space), but the string must already be prepared.

Example:

       MIOS32_MIDI_SendDebugString("ERROR: something strange happened in myFunction()!");

The string size isn't limited.

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugStringBody | ( | mios32_midi_port_t | port,
|  | char * | str,
|  | u32 | len |
| ) |  |  |

Sends the body of a debug string

Example: see MIOS32_MIDI_SendDebugStringHeader

The string size isn't limited.

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugStringFooter | ( | mios32_midi_port_t | port | ) |

Sends the footer of a debug string

Example: see MIOS32_MIDI_SendDebugStringHeader

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendDebugStringHeader | ( | mios32_midi_port_t | port,
|  | char | command,
|  | char | first_byte |
| ) |  |  |

Sends the header of a debug string

Example (implementation of MIOS32_MIDI_SendDebugString)

       u32 len = strlen(str);

       MIOS32_MIDI_SendDebugStringHeader(port, 0x40, str[0]);
       if( len >= 2 )
         MIOS32_MIDI_SendDebugStringBody(port, (char *)&str[1], len-1);
       MIOS32_MIDI_SendDebugStringFooter(port);

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 MIOS32_MIDI_SendEvent | ( | mios32_midi_port_t | port,
|  | u8 | evnt0,
|  | u8 | evnt1,
|  | u8 | evnt2 |
| ) |  |  |

Sends a MIDI Event This function is provided for a more comfortable use model o MIOS32_MIDI_SendNoteOff(port, chn, note, vel) o MIOS32_MIDI_SendNoteOn(port, chn, note, vel) o MIOS32_MIDI_SendPolyAftertouch(port, chn, note, val) o MIOS32_MIDI_SendCC(port, chn, cc, val) o MIOS32_MIDI_SendProgramChange(port, chn, prg) o MIOS32_MIDI_ChannelAftertouch(port, chn, val) o MIOS32_MIDI_PitchBend(port, chn, val)

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | evnt0 | first MIDI byte
  `[in]` | evnt1 | second MIDI byte
  `[in]` | evnt2 | third MIDI byte

Returns:
  -1 if port not available
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_SendMTC | ( | mios32_midi_port_t | port,
|  | u8 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendNoteOff | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | note,
|  | u8 | vel |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendNoteOn | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | note,
|  | u8 | vel |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendPackage | ( | mios32_midi_port_t | port,
|  | mios32_midi_package_t | package |
| ) |  |  |

Sends a package over given port This is a low level function - use the remaining MIOS32_MIDI_Send* functions to send specific MIDI events (blocking function)

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | package | MIDI package

Returns:
  -1 if port not available
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_SendPackage_NonBlocking | ( | mios32_midi_port_t | port,
|  | mios32_midi_package_t | package |
| ) |  |  |

Sends a package over given port

This is a low level function. In difference to other MIOS32_MIDI_Send* functions, It allows to send packages in non-blocking mode (caller has to retry if -2 is returned)

Before the package is forwarded, an optional Tx Callback function will be called which allows to filter/monitor/route the package, or extend the MIDI transmitter by custom MIDI Output ports (e.g. for internal busses, OSC, AOUT, etc.)

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | package | MIDI package

Returns:
  -1 if port not available
  -2 buffer is full caller should retry until buffer is free again
  -3 Tx Callback reported an error
  1 if package has been filtered by Tx callback
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_SendPackageToRxCallback | ( | mios32_midi_port_t | port,
|  | mios32_midi_package_t | midi_package |
| ) |  |  |

This function is used by MIOS32 internal functions to forward received MIDI packages to the Rx Callback routine (byte by byte)

It shouldn't be used by applications.

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | midi_package | received MIDI package

Returns:
  < 0 on errors

s32 MIOS32_MIDI_SendPitchBend | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u16 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendPolyPressure | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | note,
|  | u8 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendProgramChange | ( | mios32_midi_port_t | port,
|  | mios32_midi_chn_t | chn,
|  | u8 | prg |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendReset | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendSongPosition | ( | mios32_midi_port_t | port,
|  | u16 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendSongSelect | ( | mios32_midi_port_t | port,
|  | u8 | val |
| ) |  |  |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendSpecialEvent | ( | mios32_midi_port_t | port,
|  | u8 | type,
|  | u8 | evnt0,
|  | u8 | evnt1,
|  | u8 | evnt2 |
| ) |  |  |

Sends a special type MIDI Event This function is provided for a more comfortable use model It is aliased to following functions o MIOS32_MIDI_SendMTC(port, val) o MIOS32_MIDI_SendSongPosition(port, val) o MIOS32_MIDI_SendSongSelect(port, val) o MIOS32_MIDI_SendTuneRequest() o MIOS32_MIDI_SendClock() o MIOS32_MIDI_SendTick() o MIOS32_MIDI_SendStart() o MIOS32_MIDI_SendStop() o MIOS32_MIDI_SendContinue() o MIOS32_MIDI_SendActiveSense() o MIOS32_MIDI_SendReset()

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | type | the event type
  `[in]` | evnt0 | first MIDI byte
  `[in]` | evnt1 | second MIDI byte
  `[in]` | evnt2 | third MIDI byte

Returns:
  -1 if port not available
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_SendStart | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendStop | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendSysEx | ( | mios32_midi_port_t | port,
|  | u8 * | stream,
|  | u32 | count |
| ) |  |  |

Sends a SysEx Stream

This function is provided for a more comfortable use model

Parameters:

  `[in]` | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART3, IIC0..IIC7, SPIM0..SPIM7)
  `[in]` | stream | pointer to SysEx stream
  `[in]` | count | number of bytes

Returns:
  -1 if port not available
  0 on success

Here is the call graph for this function:

s32 MIOS32_MIDI_SendTick | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SendTuneRequest | ( | mios32_midi_port_t | port | ) |

Here is the call graph for this function:

s32 MIOS32_MIDI_SysExCallback_Init | ( | s32(*)(mios32_midi_port_t port, u8 midi_in) | callback_sysex | ) |

Installs an optional SysEx callback which is called by MIOS32_MIDI_Receive_Handler() to simplify the parsing of SysEx streams.

Without this callback (or with MIOS32_MIDI_SysExCallback_Init(NULL)), SysEx messages are only forwarded to APP_MIDI_NotifyPackage() in chunks of 1, 2 or 3 bytes, tagged with midi_package.type == 0x4..0x7 or 0xf

In this case, the application has to take care for different transmission approaches which are under control of the package sender. E.g., while Windows uses Package Type 4..7 to transmit a SysEx stream, PortMIDI under MacOS sends a mix of 0xf (single byte) and 0x4 (continued 3-byte) packages instead.

By using the SysEx callback, the type of package doesn't play a role anymore, instead the application can parse a serial stream.

MIOS32 ensures, that realtime events (0xf8..0xff) are still forwarded to APP_MIDI_NotifyPackage(), regardless if they are transmitted in a package type 0x5 or 0xf, so that the SysEx parser doesn't need to filter out such events, which could otherwise appear inside a SysEx stream.

Parameters:

  `[in]` | *callback_sysex | pointer to callback function:
          s32 callback_sysex(mios32_midi_port_t port, u8 sysex_byte)
          {
             //
             // .. parse stream
             //

             return 1; // don't forward package to APP_MIDI_NotifyPackage()
          }
  If the function returns 0, SysEx bytes will be forwarded to APP_MIDI_NotifyPackage() as well. With return value != 0, APP_MIDI_NotifyPackage() won't get the already processed package.

Returns:
  < 0 on errors

s32 MIOS32_MIDI_TimeOutCallback_Init | ( | s32(*)(mios32_midi_port_t port) | callback_timeout | ) |

Installs the Timeout callback function which is executed on incomplete MIDI packages received via UART, or on incomplete SysEx streams.

A timeout is detected after 1 second.

On a timeout, it is recommented to reset MIDI parsing relevant variables, e.g. the state of a SysEx parser.

Example:

     s32 NOTIFY_MIDI_TimeOut(mios32_midi_port_t port)
     {
       // if my SysEx parser receives a command (MY_SYSEX flag set), abort parser if port matches
       if( sysex_state.general.MY_SYSEX && port == last_sysex_port )
         MySYSEX_CmdFinished();

       return 0; // no error
     }

The callback function has been installed in an Init() function with:

       MIOS32_MIDI_TimeOutCallback_Init(NOTIFY_MIDI_TimeOut)
       {
       }

Parameters:

  `[in]` | callback_timeout | the callback function (NULL disables the callback)

Returns:
  < 0 on errors

## Variable Documentation

struct { ... } `[inherited]`

unsigned { ... } ::CMD`[inherited]`

unsigned { ... } ::CMD`[inherited]`

unsigned sysex_state_t::CMD`[inherited]`

unsigned { ... } ::CTR`[inherited]`

unsigned { ... } ::CTR`[inherited]`

struct { ... } sysex_state_t::general`[inherited]`

unsigned { ... } ::iic_receives`[inherited]`

unsigned long long sysex_timeout_ctr_flags_t::iic_receives`[inherited]`

const u8 mios32_midi_expected_bytes_common[8]

Initial value:

     {
      2,
      2,
      2,
      2,
      1,
      1,
      2,
      0,
    }

Number if expected bytes for a common MIDI event - 1.

const u8 mios32_midi_expected_bytes_system[16]

Initial value:

     {
      1,
      1,
      2,
      1,
      0,
      0,
      0,
      0,

      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
    }

Number if expected bytes for a system MIDI event - 1.

const u8 mios32_midi_pcktype_num_bytes[16]

Initial value:

     {
      0,
      0,
      2,
      3,
      3,
      1,
      2,
      3,
      3,
      3,
      3,
      3,
      2,
      2,
      3,
      1
    }

this global array is read from MIOS32_IIC_MIDI and MIOS32_UART_MIDI to determine the number of MIDI bytes which are part of a package

const u8 mios32_midi_sysex_header[5] = { 0xf0, 0x00, 0x00, 0x7e, 0x32 }

should only be used by MIOS32 internally and by the Bootloader!

unsigned { ... } ::MY_SYSEX`[inherited]`

unsigned { ... } ::MY_SYSEX`[inherited]`

unsigned sysex_state_t::MY_SYSEX`[inherited]`

struct { ... } sysex_state_t::ping`[inherited]`

unsigned { ... } ::PING_BYTE_RECEIVED`[inherited]`

unsigned sysex_state_t::PING_BYTE_RECEIVED`[inherited]`

unsigned { ... } ::spi_receives`[inherited]`

unsigned long long sysex_timeout_ctr_flags_t::spi_receives`[inherited]`

unsigned { ... } ::usb_receives`[inherited]`