MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
SerialSpec.hpp
Go to the documentation of this file.
1#pragma once
2
5
6namespace MayaFlux::Core {
7
8/**
9 * @brief A user parser: one message to a value, or nothing to drop it.
10 *
11 * The device id and source type of the result are set by the device. It runs on the
12 * link's thread, so it should be quick.
13 */
14using SerialParser = std::function<std::optional<InputValue>(Transitive::Protocol::Message message)>;
15
16/**
17 * @struct SerialSpec
18 * @brief What a serial device is: its line setup, framing and parsing, as a plain value.
19 *
20 * Start from a framing factory and refine with the chained setters, each of which
21 * returns a changed copy.
22 *
23 * @code
24 * const auto board = SerialSpec::lines().baud(115200).dtr_on_open(false).settle_ms(1500);
25 * const auto din = SerialSpec::midi();
26 * const auto frames = SerialSpec::cobs().baud(921600).parse_with(
27 * [](Transitive::Protocol::Message m) -> std::optional<InputValue> { return {}; });
28 * @endcode
29 */
30struct MAYAFLUX_API SerialSpec {
33 std::vector<uint8_t> terminator;
34 std::chrono::milliseconds gap { 2 };
35 size_t message_limit { 4096 };
38
39 [[nodiscard]] static SerialSpec lines()
40 {
41 return {};
42 }
43
44 /** @brief Messages ended by @p terminator, of one or more bytes. Empty means LF. */
45 [[nodiscard]] static SerialSpec delimited(std::string_view terminator)
46 {
47 SerialSpec spec;
49 spec.terminator.assign(terminator.begin(), terminator.end());
50 return spec;
51 }
52
53 [[nodiscard]] static SerialSpec cobs()
54 {
55 SerialSpec spec;
58 return spec;
59 }
60
61 [[nodiscard]] static SerialSpec slip()
62 {
63 SerialSpec spec;
66 return spec;
67 }
68
69 /** @brief Messages ended by @p gap of silence. Rounded up to whole milliseconds. */
70 [[nodiscard]] static SerialSpec idle_gap(std::chrono::milliseconds gap)
71 {
72 SerialSpec spec;
75 spec.gap = gap;
76 return spec;
77 }
78
79 [[nodiscard]] static SerialSpec raw()
80 {
81 SerialSpec spec;
84 return spec;
85 }
86
87 /** @brief A MIDI byte stream at 31250 baud: channel voice messages and real-time bytes. SysEx and system common messages are skipped. */
88 [[nodiscard]] static SerialSpec midi()
89 {
90 SerialSpec spec;
93 spec.line.baud_rate = 31250;
94 return spec;
95 }
96
97 [[nodiscard]] SerialSpec baud(uint32_t rate) const
98 {
99 SerialSpec copy = *this;
100 copy.line.baud_rate = rate;
101 return copy;
102 }
103
104 [[nodiscard]] SerialSpec data_bits(uint8_t bits) const
105 {
106 SerialSpec copy = *this;
107 copy.line.data_bits = bits;
108 return copy;
109 }
110
111 [[nodiscard]] SerialSpec parity(SerialParity value) const
112 {
113 SerialSpec copy = *this;
114 copy.line.parity = value;
115 return copy;
116 }
117
118 [[nodiscard]] SerialSpec stop_bits(SerialStopBits value) const
119 {
120 SerialSpec copy = *this;
121 copy.line.stop_bits = value;
122 return copy;
123 }
124
125 [[nodiscard]] SerialSpec flow_control(SerialFlowControl value) const
126 {
127 SerialSpec copy = *this;
128 copy.line.flow_control = value;
129 return copy;
130 }
131
132 [[nodiscard]] SerialSpec dtr_on_open(bool level) const
133 {
134 SerialSpec copy = *this;
135 copy.line.dtr_on_open = level;
136 return copy;
137 }
138
139 [[nodiscard]] SerialSpec rts_on_open(bool level) const
140 {
141 SerialSpec copy = *this;
142 copy.line.rts_on_open = level;
143 return copy;
144 }
145
146 /** @brief How long the port stays unread after it opens, for boards that restart on open. */
147 [[nodiscard]] SerialSpec settle_ms(uint32_t milliseconds) const
148 {
149 SerialSpec copy = *this;
150 copy.line.settle_ms = milliseconds;
151 return copy;
152 }
153
154 /** @brief The longest message in bytes. A longer one is dropped and counted. */
155 [[nodiscard]] SerialSpec max_message(size_t bytes) const
156 {
157 SerialSpec copy = *this;
158 copy.message_limit = bytes;
159 return copy;
160 }
161
162 [[nodiscard]] SerialSpec numbers() const
163 {
164 SerialSpec copy = *this;
165 copy.parse = SerialParse::NUMBERS;
166 return copy;
167 }
168
169 [[nodiscard]] SerialSpec bytes() const
170 {
171 SerialSpec copy = *this;
172 copy.parse = SerialParse::BYTES;
173 return copy;
174 }
175
176 [[nodiscard]] SerialSpec parse_with(SerialParser parser_function) const
177 {
178 SerialSpec copy = *this;
179 copy.parse = SerialParse::CUSTOM;
180 copy.parser = std::move(parser_function);
181 return copy;
182 }
183
184 /** @brief The spec a configured port describes. */
185 [[nodiscard]] static SerialSpec from(const SerialLineSettings& line, const SerialProtocolSettings& protocol)
186 {
187 SerialSpec spec;
188 spec.line = line;
189 spec.framing = protocol.framing;
190 spec.terminator.assign(protocol.terminator.begin(), protocol.terminator.end());
191 spec.gap = std::chrono::milliseconds(protocol.gap_ms);
192 spec.message_limit = protocol.message_limit;
193 spec.parse = protocol.parse;
194 return spec;
195 }
196
197 /** @brief The terminator of DELIMITED framing, LF when none was given. */
198 [[nodiscard]] std::vector<uint8_t> delimiter() const
199 {
200 return terminator.empty() ? std::vector<uint8_t> { static_cast<uint8_t>('\n') } : terminator;
201 }
202};
203
204} // namespace MayaFlux::Core
SerialStopBits
Stop bits of a serial line.
SerialParity
Parity bit of a serial line.
std::function< std::optional< InputValue >(Transitive::Protocol::Message message)> SerialParser
A user parser: one message to a value, or nothing to drop it.
SerialParse
What a message becomes.
SerialFlowControl
Flow control of a serial line: XON/XOFF in software, or RTS/CTS in hardware.
SerialFraming
How the bytes of a port are cut into messages.
std::span< const uint8_t > Message
One complete message.
Definition Framing.hpp:8
Line setup applied when a serial endpoint opens.
How a port is read, as plain data a config can hold.
SerialSpec bytes() const
SerialLineSettings line
static SerialSpec cobs()
std::vector< uint8_t > delimiter() const
The terminator of DELIMITED framing, LF when none was given.
SerialSpec parse_with(SerialParser parser_function) const
static SerialSpec midi()
A MIDI byte stream at 31250 baud: channel voice messages and real-time bytes.
SerialSpec max_message(size_t bytes) const
The longest message in bytes.
SerialSpec settle_ms(uint32_t milliseconds) const
How long the port stays unread after it opens, for boards that restart on open.
static SerialSpec from(const SerialLineSettings &line, const SerialProtocolSettings &protocol)
The spec a configured port describes.
std::chrono::milliseconds gap
static SerialSpec delimited(std::string_view terminator)
Messages ended by terminator, of one or more bytes.
static SerialSpec slip()
static SerialSpec raw()
static SerialSpec idle_gap(std::chrono::milliseconds gap)
Messages ended by gap of silence.
SerialSpec data_bits(uint8_t bits) const
SerialSpec parity(SerialParity value) const
SerialSpec rts_on_open(bool level) const
SerialSpec baud(uint32_t rate) const
static SerialSpec lines()
SerialSpec numbers() const
SerialSpec stop_bits(SerialStopBits value) const
SerialSpec dtr_on_open(bool level) const
std::vector< uint8_t > terminator
SerialSpec flow_control(SerialFlowControl value) const
What a serial device is: its line setup, framing and parsing, as a plain value.