Skip to content

Commit 9e3eb51

Browse files
author
Franz Detro
committed
improve documentation for flex data and sreeam messages
1 parent 214a5c2 commit 9e3eb51

File tree

2 files changed

+367
-259
lines changed

2 files changed

+367
-259
lines changed

‎docs/flex_data_message.md‎

Lines changed: 102 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,110 @@
11
# Flex Data Messages
22

3-
_WORK IN PROGRESS_
4-
53
Code examples can be found in [`flex_data_message.examples.cpp`](flex_data_message.examples.cpp).
64

7-
## Base Type
8-
9-
struct flex_data_message : universal_packet
10-
{
11-
flex_data_message(
12-
group_t, packet_format, packet_address, uint4_t, status_t, status_t, uint32_t = 0, uint32_t = 0, uint32_t = 0);
13-
14-
packet_format format() const;
15-
packet_address address() const;
16-
status_t status_bank() const;
17-
status_t status() const;
18-
19-
std::string payload_as_string() const;
20-
static std::string payload_as_string(const universal_packet&);
21-
};
22-
23-
bool is_flex_data_message(const universal_packet&);
24-
25-
26-
### Factory Functions
27-
28-
flex_data_message make_flex_data_message(group_t,
29-
packet_format,
30-
packet_address,
31-
uint4_t channel,
32-
status_t status_bank,
33-
status_t status,
34-
uint32_t data1 = 0,
35-
uint32_t data2 = 0,
36-
uint32_t data3 = 0);
37-
flex_data_message make_flex_data_text_message(group_t,
38-
packet_format,
39-
packet_address,
40-
uint4_t channel,
41-
status_t status_bank,
42-
status_t status,
43-
const std::string_view& text);
44-
45-
flex_data_message make_set_tempo_message(group_t, uint32_t ten_ns_per_quarter_note);
46-
flex_data_message make_set_time_signature_message(group_t,
47-
uint8_t numerator,
48-
uint8_t denominator,
49-
uint8_t nr_32rd_notes);
50-
flex_data_message make_set_metronome_message(group_t,
51-
uint8_t num_clocks_per_primary_click,
52-
uint8_t bar_accent_part1,
53-
uint8_t bar_accent_part2,
54-
uint8_t bar_accent_part3,
55-
uint8_t num_subdivision_clicks1,
56-
uint8_t num_subdivision_clicks2);
57-
flex_data_message make_set_key_signature_message(
58-
group_t, packet_address, uint4_t channel, uint4_t sharps_or_flats, uint4_t tonic_note);
59-
flex_data_message make_set_chord_message(
60-
group_t, packet_address, uint4_t channel, uint32_t data1, uint32_t data2, uint32_t data3);
5+
## Message Creation and Filtering
6+
7+
Flex Data Messages are represented by a
8+
9+
```cpp
10+
struct flex_data_message : universal_packet
11+
{
12+
flex_data_message(
13+
group_t group, packet_format format, packet_address address,
14+
channel_t channel, status_t status_bank, status_t status,
15+
uint32_t data1, uint32_t data2, uint32_t data3);
16+
17+
packet_format format() const;
18+
packet_address address() const;
19+
status_t status_bank() const;
20+
status_t status() const;
21+
22+
std::string payload_as_string() const;
23+
static std::string payload_as_string(const universal_packet&);
24+
};
25+
```
26+
27+
`packet_adress` can be `channel (0b00)` or `group (0b01)`. Use the `channel` parameter to specify a channel in `channel` address mode (will be ignored in `group` address mode).
28+
Instead of using `flex_data_message` constructors one can create messages using factory functions:
29+
30+
```cpp
31+
flex_data_message make_flex_data_message(
32+
group_t, packet_format, packet_address,
33+
uint4_t channel, status_t status_bank, status_t status,
34+
uint32_t data1 = 0, uint32_t data2 = 0, uint32_t data3 = 0);
35+
36+
flex_data_message make_flex_data_text_message(
37+
group_t, packet_format, packet_address,
38+
uint4_t channel, status_t status_bank, status_t status,
39+
const std::string_view& text);
40+
41+
flex_data_message make_set_tempo_message(group_t, uint32_t ten_ns_per_quarter_note);
42+
43+
flex_data_message make_set_time_signature_message(
44+
group_t, uint8_t numerator, uint8_t denominator, uint8_t nr_32rd_notes);
45+
46+
flex_data_message make_set_metronome_message(
47+
group_t, uint8_t num_clocks_per_primary_click,
48+
uint8_t bar_accent_part1, uint8_t bar_accent_part2, uint8_t bar_accent_part3,
49+
uint8_t num_subdivision_clicks1, uint8_t num_subdivision_clicks2);
50+
51+
flex_data_message make_set_key_signature_message(
52+
group_t, packet_address, uint4_t channel, uint4_t sharps_or_flats, uint4_t tonic_note);
53+
54+
flex_data_message make_set_chord_message(
55+
group_t, packet_address, uint4_t channel, uint32_t data1, uint32_t data2, uint32_t data3);
56+
```
57+
58+
Be aware that a single `flex_data_text_message` can hold only 12 charaters, if the text is larger you have to send a sequence of packets
59+
using the `packet_format` mechanism (`start`, `cont`, `end`).
60+
61+
Filtering of Flex Data Messages can be done checking `universal_packet::type()` against
62+
`packet_type::flex_data` or use
6163

64+
```cpp
65+
bool is_flex_data_message(const universal_packet&);
66+
```
6267
6368
### Flex Data Message Data View:
6469
65-
struct flex_data_message_view
66-
{
67-
explicit flex_data_message_view(const universal_packet&);
68-
69-
group_t group() const;
70-
packet_format format() const;
71-
packet_address address() const;
72-
channel_t channel() const;
73-
status_t status_bank() const;
74-
status_t status() const;
75-
uint32_t data1() const;
76-
uint32_t data2() const;
77-
uint32_t data3() const;
78-
uint8_t data_byte1() const;
79-
uint8_t data_byte2() const;
80-
uint8_t data_byte2() const;
81-
uint8_t data_byte3() const;
82-
uint8_t data_byte2() const;
83-
uint8_t data_byte4() const;
84-
uint8_t data_byte5() const;
85-
uint8_t data_byte6() const;
86-
uint8_t data_byte7() const;
87-
uint8_t data_byte8() const;
88-
89-
const std::string payload_as_string() const;
90-
};
91-
92-
std::optional<flex_data_message_view> as_flex_data_message_view(const universal_packet&);
70+
Once validated being a `flex_data` packet one can create a `flex_data_message_view`
71+
for a `universal_packet`:
72+
73+
```cpp
74+
struct flex_data_message_view
75+
{
76+
explicit flex_data_message_view(const universal_packet&);
77+
78+
group_t group() const;
79+
packet_format format() const;
80+
packet_address address() const;
81+
channel_t channel() const;
82+
status_t status_bank() const;
83+
status_t status() const;
84+
uint32_t data1() const;
85+
uint32_t data2() const;
86+
uint32_t data3() const;
87+
uint8_t data_byte1() const;
88+
uint8_t data_byte2() const;
89+
uint8_t data_byte2() const;
90+
uint8_t data_byte3() const;
91+
uint8_t data_byte2() const;
92+
uint8_t data_byte4() const;
93+
uint8_t data_byte5() const;
94+
uint8_t data_byte6() const;
95+
uint8_t data_byte7() const;
96+
uint8_t data_byte8() const;
97+
98+
const std::string payload_as_string() const;
99+
};
100+
```
101+
View members provide accessors to the properties of the message.
102+
In case of Flex Data Text Messages you can retrieve the message payload using `payload_as_string()`.
103+
104+
The additional
105+
106+
```cpp
107+
std::optional<flex_data_message_view> as_flex_data_message_view(const universal_packet&);
108+
```
109+
110+
helper allows to combine packet type check and view creation in a single statement.

0 commit comments

Comments
 (0)