tmk_core/protocol/midi/midi.h

   1 //midi for embedded chips,
   2 //Copyright 2010 Alex Norman
   3 //
   4 //This file is part of avr-midi.
   5 //
   6 //avr-midi is free software: you can redistribute it and/or modify
   7 //it under the terms of the GNU General Public License as published by
   8 //the Free Software Foundation, either version 3 of the License, or
   9 //(at your option) any later version.
  10 //
  11 //avr-midi is distributed in the hope that it will be useful,
  12 //but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 //MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 //GNU General Public License for more details.
  15 //
  16 //You should have received a copy of the GNU General Public License
  17 //along with avr-midi.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 /**
  20  * @file
  21  * @brief The main midi functions
  22  *
  23  * This file includes all of the functions you need to set up and process a
  24  * midi device, send midi, and register midi callbacks.
  25  *
  26  */
  27
  28 #ifndef XNOR_MIDI_H
  29 #define XNOR_MIDI_H
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #include "midi_device.h"
  36 #include "midi_function_types.h"
  37
  38 /**
  39  * @defgroup midi_device_setup_process Device initialization and processing
  40  * @brief These are method that you must use to initialize and run a device
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * @brief Initialize a device
  47  *
  48  * You must call this before using the device in question.
  49  *
  50  * @param device the device to initialize
  51 */
  52 void midi_device_init(MidiDevice * device); // [implementation in midi_device.c]
  53
  54 /**
  55  * @brief Process input data
  56  *
  57  * This method drives the input processing, you must call this method frequently
  58  * if you expect to have your input callbacks called.
  59  *
  60  * @param device the device to process
  61 */
  62 void midi_device_process(MidiDevice * device); // [implementation in midi_device.c]
  63
  64 /**@}*/
  65
  66 /**
  67  * @defgroup send_functions Midi send functions
  68  * @brief These are the functions you use to send midi data through a device.
  69  * @{
  70  */
  71
  72 /**
  73  * @brief Send a control change message (cc) via the given device.
  74  *
  75  * @param device the device to use for sending
  76  * @param chan the channel to send on, 0-15
  77  * @param num the cc num
  78  * @param val the value of that cc num
  79 */
  80 void midi_send_cc(MidiDevice * device, uint8_t chan, uint8_t num, uint8_t val);
  81
  82 /**
  83  * @brief Send a note on message via the given device.
  84  *
  85  * @param device the device to use for sending
  86  * @param chan the channel to send on, 0-15
  87  * @param num the note number
  88  * @param vel the note velocity
  89 */
  90 void midi_send_noteon(MidiDevice * device, uint8_t chan, uint8_t num, uint8_t vel);
  91
  92 /**
  93  * @brief Send a note off message via the given device.
  94  *
  95  * @param device the device to use for sending
  96  * @param chan the channel to send on, 0-15
  97  * @param num the note number
  98  * @param vel the note velocity
  99 */
 100 void midi_send_noteoff(MidiDevice * device, uint8_t chan, uint8_t num, uint8_t vel);
 101
 102 /**
 103  * @brief Send an after touch message via the given device.
 104  *
 105  * @param device the device to use for sending
 106  * @param chan the channel to send on, 0-15
 107  * @param note_num the note number
 108  * @param amt the after touch amount
 109 */
 110 void midi_send_aftertouch(MidiDevice * device, uint8_t chan, uint8_t note_num, uint8_t amt);
 111
 112 /**
 113  * @brief Send a pitch bend message via the given device.
 114  *
 115  * @param device the device to use for sending
 116  * @param chan the channel to send on, 0-15
 117  * @param amt the bend amount range: -8192..8191, 0 means no bend
 118 */
 119 void midi_send_pitchbend(MidiDevice * device, uint8_t chan, int16_t amt); //range -8192, 8191
 120
 121 /**
 122  * @brief Send a program change message via the given device.
 123  *
 124  * @param device the device to use for sending
 125  * @param chan the channel to send on, 0-15
 126  * @param num the program to change to
 127 */
 128 void midi_send_programchange(MidiDevice * device, uint8_t chan, uint8_t num);
 129
 130 /**
 131  * @brief Send a channel pressure message via the given device.
 132  *
 133  * @param device the device to use for sending
 134  * @param chan the channel to send on, 0-15
 135  * @param amt the amount of channel pressure
 136 */
 137 void midi_send_channelpressure(MidiDevice * device, uint8_t chan, uint8_t amt);
 138
 139 /**
 140  * @brief Send a clock message via the given device.
 141  *
 142  * @param device the device to use for sending
 143  */
 144 void midi_send_clock(MidiDevice * device);
 145
 146 /**
 147  * @brief Send a tick message via the given device.
 148  *
 149  * @param device the device to use for sending
 150  */
 151 void midi_send_tick(MidiDevice * device);
 152
 153 /**
 154  * @brief Send a start message via the given device.
 155  *
 156  * @param device the device to use for sending
 157  */
 158 void midi_send_start(MidiDevice * device);
 159
 160 /**
 161  * @brief Send a continue message via the given device.
 162  *
 163  * @param device the device to use for sending
 164  */
 165 void midi_send_continue(MidiDevice * device);
 166
 167 /**
 168  * @brief Send a stop message via the given device.
 169  *
 170  * @param device the device to use for sending
 171  */
 172 void midi_send_stop(MidiDevice * device);
 173
 174 /**
 175  * @brief Send an active sense message via the given device.
 176  *
 177  * @param device the device to use for sending
 178  */
 179 void midi_send_activesense(MidiDevice * device);
 180
 181 /**
 182  * @brief Send a reset message via the given device.
 183  *
 184  * @param device the device to use for sending
 185  */
 186 void midi_send_reset(MidiDevice * device);
 187
 188
 189 /**
 190  * @brief Send a tc quarter frame message via the given device.
 191  *
 192  * @param device the device to use for sending
 193  * @param time the time of this quarter frame, range 0..16383
 194  */
 195 void midi_send_tcquarterframe(MidiDevice * device, uint8_t time);
 196
 197 /**
 198  * @brief Send a song position message via the given device.
 199  *
 200  * @param device the device to use for sending
 201  * @param pos the song position
 202  */
 203 void midi_send_songposition(MidiDevice * device, uint16_t pos);
 204
 205 /**
 206  * @brief Send a song select message via the given device.
 207  *
 208  * @param device the device to use for sending
 209  * @param song the song to select
 210  */
 211 void midi_send_songselect(MidiDevice * device, uint8_t song);
 212
 213 /**
 214  * @brief Send a tune request message via the given device.
 215  *
 216  * @param device the device to use for sending
 217  */
 218 void midi_send_tunerequest(MidiDevice * device);
 219
 220 /**
 221  * @brief Send a byte via the given device.
 222  *
 223  * This is a generic method for sending data via the given midi device.
 224  * This would be useful for sending sysex data or messages that are not
 225  * implemented in this API, if there are any.  Please contact the author
 226  * if you find some so we can add them.
 227  *
 228  * @param device the device to use for sending
 229  * @param b the byte to send
 230  */
 231 void midi_send_byte(MidiDevice * device, uint8_t b);
 232
 233 /**
 234  * @brief Send up to 3 bytes of data
 235  *
 236  * % 4 is applied to count so that you can use this to pass sysex through
 237  *
 238  * @param device the device to use for sending
 239  * @param count the count of bytes to send, %4 is applied
 240  * @param byte0 the first byte
 241  * @param byte1 the second byte, ignored if cnt % 4 != 2
 242  * @param byte2 the third byte, ignored if cnt % 4 != 3
 243  */
 244 void midi_send_data(MidiDevice * device, uint16_t count, uint8_t byte0, uint8_t byte1, uint8_t byte2);
 245
 246 /**
 247  * @brief Send an array of formatted midi data.
 248  *
 249  * Can be used for sysex.
 250  *
 251  * @param device the device to use for sending
 252  * @param count the count of bytes to send
 253  * @param array the array of bytes
 254  */
 255 void midi_send_array(MidiDevice * device, uint16_t count, uint8_t * array);
 256
 257 /**@}*/
 258
 259
 260 /**
 261  * @defgroup input_callback_reg Input callback registration functions
 262  *
 263  * @brief These are the functions you use to register your input callbacks.
 264  *
 265  * The functions are called when the appropriate midi message is matched on the
 266  * associated device's input.
 267  *
 268  * @{
 269  */
 270
 271 //three byte funcs
 272
 273 /**
 274  * @brief Register a control change message (cc) callback.
 275  *
 276  * @param device the device associate with
 277  * @param func the callback function to register
 278  */
 279 void midi_register_cc_callback(MidiDevice * device, midi_three_byte_func_t func);
 280
 281 /**
 282  * @brief Register a note on callback.
 283  *
 284  * @param device the device associate with
 285  * @param func the callback function to register
 286  */
 287 void midi_register_noteon_callback(MidiDevice * device, midi_three_byte_func_t func);
 288
 289 /**
 290  * @brief Register a note off callback.
 291  *
 292  * @param device the device associate with
 293  * @param func the callback function to register
 294  */
 295 void midi_register_noteoff_callback(MidiDevice * device, midi_three_byte_func_t func);
 296
 297 /**
 298  * @brief Register an after touch callback.
 299  *
 300  * @param device the device associate with
 301  * @param func the callback function to register
 302  */
 303
 304 void midi_register_aftertouch_callback(MidiDevice * device, midi_three_byte_func_t func);
 305
 306 /**
 307  * @brief Register a pitch bend callback.
 308  *
 309  * @param device the device associate with
 310  * @param func the callback function to register
 311  */
 312 void midi_register_pitchbend_callback(MidiDevice * device, midi_three_byte_func_t func);
 313
 314 /**
 315  * @brief Register a song position callback.
 316  *
 317  * @param device the device associate with
 318  * @param func the callback function to register
 319  */
 320 void midi_register_songposition_callback(MidiDevice * device, midi_three_byte_func_t func);
 321
 322 //two byte funcs
 323
 324 /**
 325  * @brief Register a program change callback.
 326  *
 327  * @param device the device associate with
 328  * @param func the callback function to register
 329  */
 330 void midi_register_progchange_callback(MidiDevice * device, midi_two_byte_func_t func);
 331
 332 /**
 333  * @brief Register a channel pressure callback.
 334  *
 335  * @param device the device associate with
 336  * @param func the callback function to register
 337  */
 338 void midi_register_chanpressure_callback(MidiDevice * device, midi_two_byte_func_t func);
 339
 340 /**
 341  * @brief Register a song select callback.
 342  *
 343  * @param device the device associate with
 344  * @param func the callback function to register
 345  */
 346 void midi_register_songselect_callback(MidiDevice * device, midi_two_byte_func_t func);
 347
 348 /**
 349  * @brief Register a tc quarter frame callback.
 350  *
 351  * @param device the device associate with
 352  * @param func the callback function to register
 353  */
 354 void midi_register_tc_quarterframe_callback(MidiDevice * device, midi_two_byte_func_t func);
 355
 356 //one byte funcs
 357
 358 /**
 359  * @brief Register a realtime callback.
 360  *
 361  * The callback will be called for all of the real time message types.
 362  *
 363  * @param device the device associate with
 364  * @param func the callback function to register
 365  */
 366 void midi_register_realtime_callback(MidiDevice * device, midi_one_byte_func_t func);
 367
 368 /**
 369  * @brief Register a tune request callback.
 370  *
 371  * @param device the device associate with
 372  * @param func the callback function to register
 373  */
 374 void midi_register_tunerequest_callback(MidiDevice * device, midi_one_byte_func_t func);
 375
 376 /**
 377  * @brief Register a sysex callback.
 378  *
 379  * @param device the device associate with
 380  * @param func the callback function to register
 381  */
 382 void midi_register_sysex_callback(MidiDevice * device, midi_sysex_func_t func);
 383
 384 /**
 385  * @brief Register fall through callback.
 386  *
 387  * This is only called if a more specific callback is not matched and called.
 388  * For instance, if you don't register a note on callback but you get a note on message
 389  * the fall through callback will be called, if it is registered.
 390  *
 391  * @param device the device associate with
 392  * @param func the callback function to register
 393  */
 394 void midi_register_fallthrough_callback(MidiDevice * device, midi_var_byte_func_t func);
 395
 396
 397 /**
 398  * @brief Register a catch all callback.
 399  *
 400  * If registered, the catch all callback is called for every message that is
 401  * matched, even if a more specific or the fallthrough callback is registered.
 402  *
 403  * @param device the device associate with
 404  * @param func the callback function to register
 405  */
 406 void midi_register_catchall_callback(MidiDevice * device, midi_var_byte_func_t func);
 407
 408 /**@}*/
 409
 410 /**
 411  * @defgroup midi_util Device independent utility functions.
 412  * @{
 413  */
 414
 415 /**
 416  * \enum midi_packet_length_t
 417  *
 418  * An enumeration of the possible packet length values.
 419  */
 420 typedef enum {
 421    UNDEFINED = 0,
 422    ONE = 1,
 423    TWO = 2,
 424    THREE = 3} midi_packet_length_t;
 425
 426 /**
 427  * @brief Test to see if the byte given is a status byte
 428  * @param theByte the byte to test
 429  * @return true if the byte given is a midi status byte
 430  */
 431 bool midi_is_statusbyte(uint8_t theByte);
 432
 433 /**
 434  * @brief Test to see if the byte given is a realtime message
 435  * @param theByte the byte to test
 436  * @return true if it is a realtime message, false otherwise
 437  */
 438 bool midi_is_realtime(uint8_t theByte);
 439
 440 /**
 441  * @brief Find the length of the packet associated with the status byte given
 442  * @param status the status byte
 443  * @return the length of the packet, will return UNDEFINED if the byte is not
 444  * a status byte or if it is a sysex status byte
 445  */
 446 midi_packet_length_t midi_packet_length(uint8_t status);
 447
 448 /**@}*/
 449
 450 /**
 451  * @defgroup defines Midi status and miscellaneous utility #defines
 452  *
 453  * @{
 454  */
 455
 456 #define SYSEX_BEGIN 0xF0
 457 #define SYSEX_END 0xF7
 458
 459 //if you and this with a byte and you get anything non-zero
 460 //it is a status message
 461 #define MIDI_STATUSMASK 0x80
 462 //if you and this with a status message that contains channel info,
 463 //you'll get the channel
 464 #define MIDI_CHANMASK 0x0F
 465
 466 #define MIDI_CC 0xB0
 467 #define MIDI_NOTEON 0x90
 468 #define MIDI_NOTEOFF 0x80
 469 #define MIDI_AFTERTOUCH 0xA0
 470 #define MIDI_PITCHBEND 0xE0
 471 #define MIDI_PROGCHANGE 0xC0
 472 #define MIDI_CHANPRESSURE 0xD0
 473
 474 //midi realtime
 475 #define MIDI_CLOCK 0xF8
 476 #define MIDI_TICK 0xF9
 477 #define MIDI_START 0xFA
 478 #define MIDI_CONTINUE 0xFB
 479 #define MIDI_STOP 0xFC
 480 #define MIDI_ACTIVESENSE 0xFE
 481 #define MIDI_RESET 0xFF
 482
 483 #define MIDI_TC_QUARTERFRAME 0xF1
 484 #define MIDI_SONGPOSITION 0xF2
 485 #define MIDI_SONGSELECT 0xF3
 486 #define MIDI_TUNEREQUEST 0xF6
 487
 488 //This ID is for educational or development use only
 489 #define SYSEX_EDUMANUFID 0x7D
 490
 491 /**@}*/
 492
 493 #ifdef __cplusplus
 494 }
 495 #endif
 496
 497 #endif
 498