]>
code.octet-stream.net Git - m17rt/blob - m17core/src/tnc.rs
1 use crate::kiss
::{KissBuffer
, KissFrame
, PORT_PACKET_BASIC
, PORT_PACKET_FULL
, PORT_STREAM
};
2 use crate::modem
::ModulatorFrame
;
4 Frame
, LichCollection
, LsfFrame
, Mode
, PacketFrame
, PacketFrameCounter
, StreamFrame
,
7 /// Handles the KISS protocol and frame management for `SoftModulator` and `SoftDemodulator`.
9 /// These components work alongside each other. User is responsible for chaining them together
10 /// or doing something else with the data.
12 /// Handle framing of KISS commands from the host, which may arrive in arbitrary binary blobs.
13 kiss_buffer
: KissBuffer
,
15 /// Kiss message that needs to be sent to the host.
16 outgoing_kiss
: Option
<OutgoingKiss
>,
18 /// Current RX or TX function of the TNC.
21 /// Latest state of data carrier detect from demodulator - controls whether we can go to TX
24 /// Current monotonic time, counted in samples
27 // TODO: use a static ring buffer crate of some sort?
28 /// Circular buffer of packets enqueued for transmission
29 packet_queue
: [PendingPacket
; 4],
34 /// Current packet index, which is either partly transmitted or not transmitted at all.
37 /// If true, packet_next == packet_curr implies full queue. packet_next is invalid.
38 /// If false, it implies empty queue.
41 /// The LSF for a stream we are going to start transmitting.
43 /// This serves as a general indicator that we want to tx a stream.
44 stream_pending_lsf
: Option
<LsfFrame
>,
46 /// Circular buffer of stream data enqueued for transmission.
48 /// When the queue empties out, we hope that the last one has the end-of-stream flag set.
49 /// Otherwise a buffer underrun has occurred.
51 /// Overruns are less troublesome - we can drop frames and receiving stations should cope.
52 stream_queue
: [StreamFrame
; 8],
57 /// Current unsent stream frame index
60 /// True if stream_next == stream_curr because the queue is full. stream_next is invalid.
63 /// Should PTT be on right now? Polled by external
68 pub fn new() -> Self {
70 kiss_buffer
: KissBuffer
::new(),
75 packet_queue
: Default
::default(),
79 stream_pending_lsf
: None
,
80 stream_queue
: Default
::default(),
88 /// Process an individual `Frame` that has been decoded by the modem.
89 pub fn handle_frame(&mut self, frame
: Frame
) {
92 // A new LSF implies a clean slate.
93 // If we were partway through decoding something else then we missed it.
96 self.state
= State
::RxPacket(RxPacketState
{
103 let kiss
= KissFrame
::new_stream_setup(&lsf
.0).unwrap
();
104 self.kiss_to_host(kiss
);
105 self.state
= State
::RxStream(RxStreamState
{ lsf
, index
: 0 });
109 Frame
::Packet(packet
) => {
110 match &mut self.state
{
111 State
::RxPacket(ref mut rx
) => {
112 match packet
.counter
{
113 PacketFrameCounter
::Frame
{ index
} => {
114 if index
== rx
.count
&& index
< 32 {
115 let start
= 25 * index
;
116 rx
.packet
[start
..(start
+ 25)].copy_from_slice(&packet
.payload
);
119 // unexpected order - something has gone wrong
120 self.state
= State
::Idle
;
123 PacketFrameCounter
::FinalFrame
{ payload_len
} => {
124 let start
= 25 * rx
.count
;
125 let end
= start
+ payload_len
;
126 rx
.packet
[start
..(start
+ payload_len
)]
127 .copy_from_slice(&packet
.payload
);
128 // TODO: compatible packets should be sent on port 0 too
130 KissFrame
::new_full_packet(&rx
.lsf
.0, &rx
.packet
[0..end
])
132 self.kiss_to_host(kiss
);
133 self.state
= State
::Idle
;
138 // Invalid transition
139 self.state
= State
::Idle
;
143 Frame
::Stream(stream
) => {
144 match &mut self.state
{
145 State
::RxStream(ref mut rx
) => {
146 // TODO: consider wraparound from 0x7fff
147 if stream
.frame
_n
umber
< rx
.index
{
148 let mut lich
= LichCollection
::new();
149 lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
150 self.state
= State
::RxAcquiringStream(RxAcquiringStreamState
{ lich
});
152 rx
.index
= stream
.frame
_n
umber
+ 1;
153 let kiss
= KissFrame
::new_stream_data(&stream
).unwrap
();
154 self.kiss_to_host(kiss
);
155 // TODO: end stream if LICH updates indicate non-META part has changed
156 // (this implies a new station)
157 if stream
.end_of_stream
{
158 self.state
= State
::Idle
;
162 State
::RxAcquiringStream(ref mut rx
) => {
163 rx
.lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
164 if let Some(maybe_lsf
) = rx
.lich
.try_assemble() {
165 let lsf
= LsfFrame(maybe_lsf
);
166 // LICH can change mid-transmission so wait until the CRC is correct
167 // to ensure (to high probability) we haven't done a "torn read"
168 if lsf
.check_crc() == 0 {
169 let kiss
= KissFrame
::new_stream_setup(&lsf
.0).unwrap
();
170 self.kiss_to_host(kiss
);
171 // TODO: avoid discarding the first data payload here
172 // need a queue depth of 2 for outgoing kiss
173 self.state
= State
::RxStream(RxStreamState
{
175 index
: stream
.frame
_n
umber
+ 1,
181 // If coming from another state, we have missed something.
182 // Never mind, let's start tracking LICH.
183 let mut lich
= LichCollection
::new();
184 lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
185 self.state
= State
::RxAcquiringStream(RxAcquiringStreamState
{ lich
})
192 pub fn set_data_carrier_detect(&mut self, dcd
: bool
) {
196 pub fn set_now(&mut self, now_samples
: u64) {
197 self.now
= now_samples
;
199 State
::TxEndingAtTime(time
) => {
200 if now_samples
>= time
{
202 self.state
= State
::Idle
;
209 pub fn ptt(&self) -> bool
{
213 pub fn set_tx_end_time(&mut self, in_samples
: usize) {
216 self.state
= State
::TxEndingAtTime(self.now
+ in_samples
as u64);
222 pub fn read_tx_frame(&mut self) -> Option
<ModulatorFrame
> {
224 State
::Idle
| State
::RxAcquiringStream(_
) | State
::RxStream(_
) | State
::RxPacket(_
) => {
225 // We will let CSMA decide whether to actually go ahead.
226 // That's not implemented yet, so let's just check DCD.
227 let channel_free
= !self.dcd
;
228 let stream_wants_to_tx
= self.stream_pending_lsf
.is
_some
();
229 let packet_wants_to_tx
= self.packet_full
|| (self.packet_next
!= self.packet_curr
);
230 if channel_free
&& stream_wants_to_tx
{
231 self.state
= State
::TxStream
;
232 } else if channel_free
&& packet_wants_to_tx
{
233 self.state
= State
::TxPacket
;
238 // TODO: true txdelay
239 Some(ModulatorFrame
::Preamble
{ tx_delay
: 0 })
242 if !self.stream_full
&& self.stream_next
== self.stream_curr
{
245 if let Some(lsf
) = self.stream_pending_lsf
.take() {
246 return Some(ModulatorFrame
::Lsf(lsf
));
248 let frame
= self.stream_queue
[self.stream_curr
].clone();
249 if self.stream_full
{
250 self.stream_full
= false;
252 self.stream_curr
= (self.stream_curr
+ 1) % 8;
253 if frame
.end_of_stream
{
254 self.state
= State
::Idle
;
256 Some(ModulatorFrame
::Stream(frame
))
258 State
::TxStreamSentEndOfStream
=> {
259 self.state
= State
::TxEnding
;
260 Some(ModulatorFrame
::EndOfTransmission
)
263 if !self.packet_full
&& self.packet_next
== self.packet_curr
{
266 while self.packet_next
!= self.packet_curr
{
267 match self.packet_queue
[self.packet_curr
].next_frame() {
272 self.packet_curr
= (self.packet_curr
+ 1) % 4;
276 self.state
= State
::TxEnding
;
277 Some(ModulatorFrame
::EndOfTransmission
)
279 State
::TxEnding
| State
::TxEndingAtTime(_
) => {
280 // Once we have signalled EOT we withold any new frames until
281 // the channel fully clears and we are ready to TX again
287 /// Read KISS message to be sent to host.
289 /// After each frame input, this should be consumed in a loop until length 0 is returned.
290 /// This component will never block. Upstream interface can provide blocking `read()` if desired.
291 pub fn read_kiss(&mut self, target_buf
: &mut [u8]) -> usize {
292 match self.outgoing_kiss
.as_mut() {
294 let n
= (outgoing
.kiss_frame
.len
- outgoing
.sent
).min(target_buf
.len());
296 .copy_from_slice(&outgoing
.kiss_frame
.data
[outgoing
.sent
..(outgoing
.sent
+ n
)]);
298 if outgoing
.sent
== outgoing
.kiss_frame
.len
{
299 self.outgoing_kiss
= None
;
307 /// Host sends in some KISS data.
308 pub fn write_kiss(&mut self, buf
: &[u8]) -> usize {
309 let target_buf
= self.kiss_buffer
.buf_remaining();
310 let n
= buf
.len().min(target_buf
.len());
311 target_buf
[0..n
].copy_from_slice(&buf
[0..n
]);
312 self.kiss_buffer
.did_write(n
);
313 while let Some(kiss_frame
) = self.kiss_buffer
.next_frame() {
314 let Ok(port
) = kiss_frame
.port() else {
317 if port
== PORT_PACKET_BASIC
{
318 } else if port
== PORT_PACKET_FULL
{
319 } else if port
== PORT_STREAM
{
325 fn kiss_to_host(&mut self, kiss_frame
: KissFrame
) {
326 self.outgoing_kiss
= Some(OutgoingKiss
{
333 #[derive(Debug, PartialEq, Eq, Clone)]
334 pub enum SoftTncError
{
335 General(&'
static str),
339 struct OutgoingKiss
{
340 kiss_frame
: KissFrame
,
345 /// Nothing happening. We may have TX data queued but we won't act on it until CSMA opens up.
348 /// We received some stream data but missed the leading LSF so we are trying to assemble from LICH.
349 RxAcquiringStream(RxAcquiringStreamState
),
351 /// We have acquired an identified stream transmission and are sending data payloads to the host.
352 RxStream(RxStreamState
),
354 /// We are receiving a packet. All is well so far, and there is more data to come before we tell the host.
355 RxPacket(RxPacketState
),
357 /// PTT is on and this is a stream-type transmission. New data may be added.
360 /// We have delivered the last frame in the current stream
361 TxStreamSentEndOfStream
,
363 /// PTT is on and this is a packet-type transmission. New packets may be enqueued.
366 /// We gave modulator an EndOfTransmission. PTT is still on, waiting for modulator to advise end time.
369 /// Ending transmission, PTT remains on, but we know the timestamp at which we should disengage it.
373 struct RxAcquiringStreamState
{
374 /// Partial assembly of LSF by accumulating LICH fields.
375 lich
: LichCollection
,
378 struct RxStreamState
{
379 /// Track identifying information for this transmission so we can tell if it changes.
382 /// Expected next frame number. Allowed to skip values on RX, but not go backwards.
386 struct RxPacketState
{
390 /// Accumulation of packet data that we have received so far.
393 /// Number of payload frames we have received. If we are stably in the RxPacket state,
394 /// this will be between 0 and 32 inclusive.
398 struct PendingPacket
{
399 lsf
: Option
<LsfFrame
>,
403 app_data_transmitted
: usize,
407 /// Returns next frame, not including preamble or EOT.
409 /// False means all data frames have been sent.
410 fn next_frame(&mut self) -> Option
<ModulatorFrame
> {
411 if let Some(lsf
) = self.lsf
.take() {
412 return Some(ModulatorFrame
::Lsf(lsf
));
414 if self.app_data_len
== self.app_data_transmitted
{
417 let remaining
= self.app_data_len
- self.app_data_transmitted
;
418 let (counter
, data_len
) = if remaining
<= 25 {
420 PacketFrameCounter
::FinalFrame
{
421 payload_len
: remaining
,
427 PacketFrameCounter
::Frame
{
428 index
: self.app_data_transmitted
/ 25,
433 let mut payload
= [0u8; 25];
434 payload
.copy_from_slice(
435 &self.app_data
[self.app_data_transmitted
..(self.app_data_transmitted
+ data_len
)],
437 self.app_data_transmitted
+= data_len
;
438 Some(ModulatorFrame
::Packet(PacketFrame
{ payload
, counter
}))
442 impl Default
for PendingPacket
{
443 fn default() -> Self {
446 app_data
: [0u8; 825],
448 app_data_transmitted
: 0,
456 use crate::kiss
::{KissCommand
, PORT_STREAM
};
457 use crate::protocol
::StreamFrame
;
459 // TODO: finish all handle_frame tests as below
460 // this will be much more straightforward when we have a way to create LSFs programatically
462 // receiving a single-frame packet
464 // receiving a multi-frame packet
466 // part of one packet and then another
469 fn tnc_receive_stream() {
471 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0,
472 0, 0, 0, 0, 0, 131, 53,
474 let stream1
= StreamFrame
{
476 lich_part
: [255, 255, 255, 255, 255],
478 end_of_stream
: false,
480 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
483 let stream2
= StreamFrame
{
485 lich_part
: [255, 0, 0, 0, 159],
489 17, 0, 94, 82, 216, 135, 181, 15, 30, 0, 125, 195, 152, 183, 41, 57,
492 let mut tnc
= SoftTnc
::new();
493 let mut kiss
= KissFrame
::new_empty();
494 assert_eq
!(tnc
.read_kiss(&mut kiss
.data
), 0);
496 tnc
.handle_frame(Frame
::Lsf(lsf
));
497 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
498 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
499 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
501 let mut payload_buf
= [0u8; 2048];
502 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
505 tnc
.handle_frame(Frame
::Stream(stream1
));
506 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
507 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
508 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
510 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
513 tnc
.handle_frame(Frame
::Stream(stream2
));
514 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
515 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
516 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
518 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
523 fn tnc_acquire_stream() {
527 lich_part
: [255, 255, 255, 255, 255],
529 end_of_stream
: false,
531 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
536 lich_part
: [255, 0, 0, 0, 159],
538 end_of_stream
: false,
540 17, 0, 94, 82, 216, 135, 181, 15, 30, 0, 125, 195, 152, 183, 41, 57,
545 lich_part
: [221, 81, 5, 5, 0],
547 end_of_stream
: false,
549 17, 128, 93, 74, 154, 167, 169, 11, 20, 0, 116, 91, 158, 220, 45, 111,
554 lich_part
: [0, 0, 0, 0, 0],
556 end_of_stream
: false,
558 15, 128, 114, 83, 218, 252, 59, 111, 31, 128, 116, 91, 84, 231, 45, 105,
563 lich_part
: [0, 0, 0, 0, 0],
565 end_of_stream
: false,
567 9, 128, 119, 115, 220, 220, 57, 15, 48, 128, 124, 83, 158, 236, 181, 91,
572 lich_part
: [0, 0, 0, 131, 53],
574 end_of_stream
: false,
576 52, 0, 116, 90, 152, 167, 225, 216, 32, 0, 116, 83, 156, 212, 33, 216,
581 let mut tnc
= SoftTnc
::new();
582 let mut kiss
= KissFrame
::new_empty();
584 tnc
.handle_frame(Frame
::Stream(f
));
586 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
587 let mut payload_buf
= [0u8; 2048];
588 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
593 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0,
594 0, 0, 0, 0, 0, 0, 131, 53,
600 fn tnc_handle_skipped_stream_frame() {
602 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0,
603 0, 0, 0, 0, 0, 131, 53,
605 let stream1
= StreamFrame
{
607 lich_part
: [255, 255, 255, 255, 255],
609 end_of_stream
: false,
611 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
614 let stream3
= StreamFrame
{
616 lich_part
: [221, 81, 5, 5, 0],
618 end_of_stream
: false,
620 17, 128, 93, 74, 154, 167, 169, 11, 20, 0, 116, 91, 158, 220, 45, 111,
623 let mut tnc
= SoftTnc
::new();
624 let mut kiss
= KissFrame
::new_empty();
625 assert_eq
!(tnc
.read_kiss(&mut kiss
.data
), 0);
627 tnc
.handle_frame(Frame
::Lsf(lsf
));
628 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
629 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
630 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
632 let mut payload_buf
= [0u8; 2048];
633 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
636 tnc
.handle_frame(Frame
::Stream(stream1
));
637 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
638 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
639 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
641 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
644 tnc
.handle_frame(Frame
::Stream(stream3
));
645 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
646 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
647 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
649 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();