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.
| s32 MIOS32_MIDI_CheckAvailable | ( | mios32_midi_port_t | port | ) |
This function checks the availability of a MIDI port
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
0: port not available
| s32 MIOS32_MIDI_DebugCommandCallback_Init | ( | void * | 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);
| [in] | callback_debug_command | the callback function (NULL disables the callback) |
| mios32_midi_port_t MIOS32_MIDI_DebugPortGet | ( | void | ) |
This function returns the MIDI_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 so long not overruled in mios32_config.h
| [in] | port | MIDI port (USB0..USB7, UART0..UART1, IIC0..IIC7) |
| mios32_midi_port_t MIOS32_MIDI_DefaultPortGet | ( | void | ) |
This function 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 so long not overruled in mios32_config.h
| [in] | port | MIDI port (USB0..USB7, UART0..UART1, IIC0..IIC7) |
| 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 via Bootloader Command 0x0c
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 Bootloader Command 0x0c
| [in] | device_id | a new (temporary) device ID (0x00..0x7f) |
| s32 MIOS32_MIDI_DirectRxCallback_Init | ( | void * | 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.
| [in] | *callback_rx | pointer to callback function:s32 callback_rx(mios32_midi_port_t port, u8 midi_byte) { } It will be filtered out if the callback returns != 0 (e.g. 1 for "filter", or -1 for "error"). |
| s32 MIOS32_MIDI_DirectTxCallback_Init | ( | void * | 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:
| [in] | *callback_tx | pointer to callback function:s32 callback_tx(mios32_midi_port_t port, mios32_midi_package_t package) { } 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() |
Initializes MIDI layer
| [in] | mode | currently only mode 0 supported |
| 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!
| [in] | uart_port | UART number (0..1) |
| s32 MIOS32_MIDI_Receive_Handler | ( | void * | _callback_package | ) |
Checks for incoming MIDI messages amd 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()
| 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.
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
0 if optimisation disabled
1 if optimisation enabled
| 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).
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | enable | 0=optimisation disabled, 1=optimisation enabled |
0 on success
| 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.
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
0 if optimisation disabled
1 if optimisation enabled
| s32 MIOS32_MIDI_SendActiveSense | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SendAftertouch | ( | mios32_midi_port_t | port, | |
| mios32_midi_chn_t | chn, | |||
| u8 | val | |||
| ) |
| 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.
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | midi_byte | received MIDI byte |
| s32 MIOS32_MIDI_SendCC | ( | mios32_midi_port_t | port, | |
| mios32_midi_chn_t | chn, | |||
| u8 | cc_number, | |||
| u8 | val | |||
| ) |
| s32 MIOS32_MIDI_SendClock | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SendContinue | ( | mios32_midi_port_t | port | ) |
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
Optionally, the port can be changed during runtime with MIOS32_MIDI_DebugPortSet
| [in] | *src | pointer to memory location which should be dumped |
| [in] | len | number of bytes which should be sent |
| s32 MIOS32_MIDI_SendDebugMessage | ( | 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
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.
| [in] | *format | zero-terminated format string - 128 characters supported maximum! |
| ... | additional arguments |
| 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)
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | evnt0 | first MIDI byte |
| [in] | evnt1 | second MIDI byte |
| [in] | evnt2 | third MIDI byte |
0 on success
| s32 MIOS32_MIDI_SendMTC | ( | mios32_midi_port_t | port, | |
| u8 | val | |||
| ) |
| 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_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)
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | package | MIDI package |
0 on success
| 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.)
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | package | MIDI package |
-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
| 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.
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | midi_package | received MIDI package |
| s32 MIOS32_MIDI_SendPitchBend | ( | mios32_midi_port_t | port, | |
| mios32_midi_chn_t | chn, | |||
| u16 | val | |||
| ) |
| s32 MIOS32_MIDI_SendPolyPressure | ( | mios32_midi_port_t | port, | |
| mios32_midi_chn_t | chn, | |||
| u8 | note, | |||
| u8 | val | |||
| ) |
| s32 MIOS32_MIDI_SendProgramChange | ( | mios32_midi_port_t | port, | |
| mios32_midi_chn_t | chn, | |||
| u8 | prg | |||
| ) |
| s32 MIOS32_MIDI_SendReset | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SendSongPosition | ( | mios32_midi_port_t | port, | |
| u16 | val | |||
| ) |
| s32 MIOS32_MIDI_SendSongSelect | ( | mios32_midi_port_t | port, | |
| u8 | val | |||
| ) |
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()
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | type | the event type |
| [in] | evnt0 | first MIDI byte |
| [in] | evnt1 | second MIDI byte |
| [in] | evnt2 | third MIDI byte |
0 on success
| s32 MIOS32_MIDI_SendStart | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SendStop | ( | mios32_midi_port_t | port | ) |
| 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
| [in] | port | MIDI port (DEFAULT, USB0..USB7, UART0..UART1, IIC0..IIC7) |
| [in] | stream | pointer to SysEx stream |
| [in] | count | number of bytes |
0 on success
| s32 MIOS32_MIDI_SendTick | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SendTuneRequest | ( | mios32_midi_port_t | port | ) |
| s32 MIOS32_MIDI_SysExCallback_Init | ( | void * | 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.
| [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() } |
| s32 MIOS32_MIDI_TimeOutCallback_Init | ( | void * | 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.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) { }
| [in] | callback_timeout | the callback function (NULL disables the callback) |
struct { ... } [inherited] |
struct { ... } [inherited] |
struct { ... } [inherited] |
unsigned { ... } ::CMD [inherited] |
unsigned { ... } ::CMD [inherited] |
unsigned sysex_state_t::CMD [inherited] |
unsigned { ... } ::CTR [inherited] |
unsigned { ... } ::CTR [inherited] |
unsigned { ... } ::iic_receives [inherited] |
unsigned 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,
}
| 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,
}
| 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
}
| 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] |
unsigned { ... } ::PING_BYTE_RECEIVED [inherited] |
unsigned sysex_state_t::PING_BYTE_RECEIVED [inherited] |
unsigned { ... } ::usb_receives [inherited] |
1.4.7