summaryrefslogtreecommitdiffstats
path: root/tmk_core/protocol/midi/midi.h
blob: 75f3b13b0bf5a7a7eda598730a2e0dffeef2b685 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
// midi for embedded chips,
// Copyright 2010 Alex Norman
//
// This file is part of avr-midi.
//
// avr-midi is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
//(at your option) any later version.
//
// avr-midi is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with avr-midi.  If not, see <http://www.gnu.org/licenses/>.

/**
 * @file
 * @brief The main midi functions
 *
 * This file includes all of the functions you need to set up and process a
 * midi device, send midi, and register midi callbacks.
 *
 */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

#include "midi_device.h"
#include "midi_function_types.h"

/**
 * @defgroup midi_device_setup_process Device initialization and processing
 * @brief These are method that you must use to initialize and run a device
 *
 * @{
 */

/**
 * @brief Initialize a device
 *
 * You must call this before using the device in question.
 *
 * @param device the device to initialize
 */
void midi_device_init(MidiDevice* device);  // [implementation in midi_device.c]

/**
 * @brief Process input data
 *
 * This method drives the input processing, you must call this method frequently
 * if you expect to have your input callbacks called.
 *
 * @param device the device to process
 */
void midi_device_process(MidiDevice* device);  // [implementation in midi_device.c]

/**@}*/

/**
 * @defgroup send_functions Midi send functions
 * @brief These are the functions you use to send midi data through a device.
 * @{
 */

/**
 * @brief Send a control change message (cc) via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param num the cc num
 * @param val the value of that cc num
 */
void midi_send_cc(MidiDevice* device, uint8_t chan, uint8_t num, uint8_t val);

/**
 * @brief Send a note on message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param num the note number
 * @param vel the note velocity
 */
void midi_send_noteon(MidiDevice* device, uint8_t chan, uint8_t num, uint8_t vel);

/**
 * @brief Send a note off message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param num the note number
 * @param vel the note velocity
 */
void midi_send_noteoff(MidiDevice* device, uint8_t chan, uint8_t num, uint8_t vel);

/**
 * @brief Send an after touch message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param note_num the note number
 * @param amt the after touch amount
 */
void midi_send_aftertouch(MidiDevice* device, uint8_t chan, uint8_t note_num, uint8_t amt);

/**
 * @brief Send a pitch bend message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param amt the bend amount range: -8192..8191, 0 means no bend
 */
void midi_send_pitchbend(MidiDevice* device, uint8_t chan, int16_t amt);  // range -8192, 8191

/**
 * @brief Send a program change message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param num the program to change to
 */
void midi_send_programchange(MidiDevice* device, uint8_t chan, uint8_t num);

/**
 * @brief Send a channel pressure message via the given device.
 *
 * @param device the device to use for sending
 * @param chan the channel to send on, 0-15
 * @param amt the amount of channel pressure
 */
void midi_send_channelpressure(MidiDevice* device, uint8_t chan, uint8_t amt);

/**
 * @brief Send a clock message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_clock(MidiDevice* device);

/**
 * @brief Send a tick message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_tick(MidiDevice* device);

/**
 * @brief Send a start message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_start(MidiDevice* device);

/**
 * @brief Send a continue message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_continue(MidiDevice* device);

/**
 * @brief Send a stop message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_stop(MidiDevice* device);

/**
 * @brief Send an active sense message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_activesense(MidiDevice* device);

/**
 * @brief Send a reset message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_reset(MidiDevice* device);

/**
 * @brief Send a tc quarter frame message via the given device.
 *
 * @param device the device to use for sending
 * @param time the time of this quarter frame, range 0..16383
 */
void midi_send_tcquarterframe(MidiDevice* device, uint8_t time);

/**
 * @brief Send a song position message via the given device.
 *
 * @param device the device to use for sending
 * @param pos the song position
 */
void midi_send_songposition(MidiDevice* device, uint16_t pos);

/**
 * @brief Send a song select message via the given device.
 *
 * @param device the device to use for sending
 * @param song the song to select
 */
void midi_send_songselect(MidiDevice* device, uint8_t song);

/**
 * @brief Send a tune request message via the given device.
 *
 * @param device the device to use for sending
 */
void midi_send_tunerequest(MidiDevice* device);

/**
 * @brief Send a byte via the given device.
 *
 * This is a generic method for sending data via the given midi device.
 * This would be useful for sending sysex data or messages that are not
 * implemented in this API, if there are any.  Please contact the author
 * if you find some so we can add them.
 *
 * @param device the device to use for sending
 * @param b the byte to send
 */
void midi_send_byte(MidiDevice* device, uint8_t b);

/**
 * @brief Send up to 3 bytes of data
 *
 * % 4 is applied to count so that you can use this to pass sysex through
 *
 * @param device the device to use for sending
 * @param count the count of bytes to send, %4 is applied
 * @param byte0 the first byte
 * @param byte1 the second byte, ignored if cnt % 4 != 2
 * @param byte2 the third byte, ignored if cnt % 4 != 3
 */
void midi_send_data(MidiDevice* device, uint16_t count, uint8_t byte0, uint8_t byte1, uint8_t byte2);

/**
 * @brief Send an array of formatted midi data.
 *
 * Can be used for sysex.
 *
 * @param device the device to use for sending
 * @param count the count of bytes to send
 * @param array the array of bytes
 */
void midi_send_array(MidiDevice* device, uint16_t count, uint8_t* array);

/**@}*/

/**
 * @defgroup input_callback_reg Input callback registration functions
 *
 * @brief These are the functions you use to register your input callbacks.
 *
 * The functions are called when the appropriate midi message is matched on the
 * associated device's input.
 *
 * @{
 */

// three byte funcs

/**
 * @brief Register a control change message (cc) callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_cc_callback(MidiDevice* device, midi_three_byte_func_t func);

/**
 * @brief Register a note on callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_noteon_callback(MidiDevice* device, midi_three_byte_func_t func);

/**
 * @brief Register a note off callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_noteoff_callback(MidiDevice* device, midi_three_byte_func_t func);

/**
 * @brief Register an after touch callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */

void midi_register_aftertouch_callback(MidiDevice* device, midi_three_byte_func_t func);

/**
 * @brief Register a pitch bend callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_pitchbend_callback(MidiDevice* device, midi_three_byte_func_t func);

/**
 * @brief Register a song position callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_songposition_callback(MidiDevice* device, midi_three_byte_func_t func);

// two byte funcs

/**
 * @brief Register a program change callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_progchange_callback(MidiDevice* device, midi_two_byte_func_t func);

/**
 * @brief Register a channel pressure callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_chanpressure_callback(MidiDevice* device, midi_two_byte_func_t func);

/**
 * @brief Register a song select callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_songselect_callback(MidiDevice* device, midi_two_byte_func_t func);

/**
 * @brief Register a tc quarter frame callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_tc_quarterframe_callback(MidiDevice* device, midi_two_byte_func_t func);

// one byte funcs

/**
 * @brief Register a realtime callback.
 *
 * The callback will be called for all of the real time message types.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_realtime_callback(MidiDevice* device, midi_one_byte_func_t func);

/**
 * @brief Register a tune request callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_tunerequest_callback(MidiDevice* device, midi_one_byte_func_t func);

/**
 * @brief Register a sysex callback.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_sysex_callback(MidiDevice* device, midi_sysex_func_t func);

/**
 * @brief Register fall through callback.
 *
 * This is only called if a more specific callback is not matched and called.
 * For instance, if you don't register a note on callback but you get a note on message
 * the fall through callback will be called, if it is registered.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_fallthrough_callback(MidiDevice* device, midi_var_byte_func_t func);

/**
 * @brief Register a catch all callback.
 *
 * If registered, the catch all callback is called for every message that is
 * matched, even if a more specific or the fallthrough callback is registered.
 *
 * @param device the device associate with
 * @param func the callback function to register
 */
void midi_register_catchall_callback(MidiDevice* device, midi_var_byte_func_t func);

/**@}*/

/**
 * @defgroup midi_util Device independent utility functions.
 * @{
 */

/**
 * \enum midi_packet_length_t
 *
 * An enumeration of the possible packet length values.
 */
typedef enum { UNDEFINED = 0, ONE = 1, TWO = 2, THREE = 3 } midi_packet_length_t;

/**
 * @brief Test to see if the byte given is a status byte
 * @param theByte the byte to test
 * @return true if the byte given is a midi status byte
 */
bool midi_is_statusbyte(uint8_t theByte);

/**
 * @brief Test to see if the byte given is a realtime message
 * @param theByte the byte to test
 * @return true if it is a realtime message, false otherwise
 */
bool midi_is_realtime(uint8_t theByte);

/**
 * @brief Find the length of the packet associated with the status byte given
 * @param status the status byte
 * @return the length of the packet, will return UNDEFINED if the byte is not
 * a status byte or if it is a sysex status byte
 */
midi_packet_length_t midi_packet_length(uint8_t status);

/**@}*/

/**
 * @defgroup defines Midi status and miscellaneous utility #defines
 *
 * @{
 */

#define SYSEX_BEGIN 0xF0
#define SYSEX_END 0xF7

// if you and this with a byte and you get anything non-zero
// it is a status message
#define MIDI_STATUSMASK 0x80
// if you and this with a status message that contains channel info,
// you'll get the channel
#define MIDI_CHANMASK 0x0F

#define MIDI_CC 0xB0
#define MIDI_NOTEON 0x90
#define MIDI_NOTEOFF 0x80
#define MIDI_AFTERTOUCH 0xA0
#define MIDI_PITCHBEND 0xE0
#define MIDI_PROGCHANGE 0xC0
#define MIDI_CHANPRESSURE 0xD0

// midi realtime
#define MIDI_CLOCK 0xF8
#define MIDI_TICK 0xF9
#define MIDI_START 0xFA
#define MIDI_CONTINUE 0xFB
#define MIDI_STOP 0xFC
#define MIDI_ACTIVESENSE 0xFE
#define MIDI_RESET 0xFF

#define MIDI_TC_QUARTERFRAME 0xF1
#define MIDI_SONGPOSITION 0xF2
#define MIDI_SONGSELECT 0xF3
#define MIDI_TUNEREQUEST 0xF6

// This ID is for educational or development use only
#define SYSEX_EDUMANUFID 0x7D

/**@}*/

#ifdef __cplusplus
}
#endif