README.rst
1.. zephyr:code-sample:: netmidi2
2 :name: MIDI2 network transport
3 :relevant-api: midi_ump net_midi2
4
5 Exchange Universal MIDI Packets over the Network MIDI 2.0 protocol
6
7Overview
8********
9
10This sample demonstrates usage of the Network MIDI 2.0 stack:
11
12* start a UMP Endpoint host reachable on the network
13* respond to UMP Stream discovery messages, so that clients can discover the
14 topology described in the device tree
15* if ``midi_serial`` port is defined in the device tree,
16 send MIDI1 data from UMP group 9 there
17* if ``midi_green_led`` node is defined in the device tree,
18 light up the led when sending data on the serial port
19
20Requirements
21************
22
23This sample requires a board with IP networking support. To perform anything
24useful against the running sample, you will also need a Network MIDI2.0 client
25to connect to the target, for example `pymidi2`_
26
27Building and Running
28********************
29
30The easiest way to try out this sample without any hardware is using
31``native_sim``. See :ref:`native_sim ethernet driver <nsim_per_ethe>` to setup
32networking on your computer accordingly
33
34.. zephyr-app-commands::
35 :zephyr-app: samples/net/midi2/
36 :board: native_sim
37 :goals: run
38
39The Network MIDI 2.0 endpoint should now be reachable on the network:
40
41.. code-block:: console
42
43 $ pymidi2 find
44 Zephyr-UDP-MIDI2 (udp://192.0.2.1:45486)
45 - Block #0 [io : Recv/Send] 'Synthesizer' UMP groups {0, 1, 2, 3} [MIDI1 + MIDI2]
46 - Block #1 [i- : Recv ] 'Keyboard' UMP groups {8} [MIDI1 only]
47 - Block #2 [-o : Send] 'External output (MIDI DIN-5)' UMP groups {9} [MIDI1 31.25kb/s]
48
49
50Furthermore, this sample pairs well with the :ref:`olimex_shield_midi`,
51that conveniently defines the device tree nodes for the external MIDI OUT
52and its led. For example, using this shield on the ST Nucleo F429zi:
53
54.. zephyr-app-commands::
55 :zephyr-app: samples/net/midi2
56 :board: nucleo_f429zi
57 :shield: olimex_shield_midi
58 :goals: build flash
59
60Using authentication
61********************
62
63To enable shared secret authentication to connect to the UMP endpoint host,
64enable :kconfig:option:`CONFIG_NET_SAMPLE_MIDI2_AUTH_SHARED_SECRET`,
65and then configure the desired shared secret in
66:kconfig:option:`CONFIG_NET_SAMPLE_MIDI2_SHARED_SECRET`
67
68To enable user/password authentication instead, enable
69:kconfig:option:`CONFIG_NET_SAMPLE_MIDI2_AUTH_USER_PASSWORD`, and then
70configure the desired username/password in
71:kconfig:option:`CONFIG_NET_SAMPLE_MIDI2_USERNAME`
72and :kconfig:option:`CONFIG_NET_SAMPLE_MIDI2_PASSWORD`
73
74.. _pymidi2:
75 https://github.com/titouanc/pymidi2
76
