]>
code.octet-stream.net Git - m17rt/blob - m17core/src/tnc.rs
93a4363ae62f0939100ee51a04166fc548595edd
1 use crate::address
::{Address
, Callsign
};
3 KissBuffer
, KissCommand
, KissFrame
, PORT_PACKET_BASIC
, PORT_PACKET_FULL
, PORT_STREAM
,
5 use crate::modem
::ModulatorFrame
;
7 Frame
, LichCollection
, LsfFrame
, Mode
, PacketFrame
, PacketFrameCounter
, StreamFrame
,
10 /// Handles the KISS protocol and frame management for `SoftModulator` and `SoftDemodulator`.
12 /// These components work alongside each other. User is responsible for chaining them together
13 /// or doing something else with the data.
15 /// Handle framing of KISS commands from the host, which may arrive in arbitrary binary blobs.
16 kiss_buffer
: KissBuffer
,
18 /// Kiss message that needs to be sent to the host.
19 outgoing_kiss
: Option
<OutgoingKiss
>,
21 /// Current RX or TX function of the TNC.
24 /// Latest state of data carrier detect from demodulator - controls whether we can go to TX
27 /// If CSMA declined to transmit into an idle slot, at what point do we next check it?
28 next_csma_check
: Option
<u64>,
30 /// Current monotonic time, counted in samples
33 // TODO: use a static ring buffer crate of some sort?
34 /// Circular buffer of packets enqueued for transmission
35 packet_queue
: [PendingPacket
; 4],
40 /// Current packet index, which is either partly transmitted or not transmitted at all.
43 /// If true, packet_next == packet_curr implies full queue. packet_next is invalid.
44 /// If false, it implies empty queue.
47 /// The LSF for a stream we are going to start transmitting.
49 /// This serves as a general indicator that we want to tx a stream.
50 stream_pending_lsf
: Option
<LsfFrame
>,
52 /// Circular buffer of stream data enqueued for transmission.
54 /// When the queue empties out, we hope that the last one has the end-of-stream flag set.
55 /// Otherwise a buffer underrun has occurred.
57 /// Overruns are less troublesome - we can drop frames and receiving stations should cope.
58 stream_queue
: [StreamFrame
; 8],
63 /// Current unsent stream frame index
66 /// True if stream_next == stream_curr because the queue is full. stream_next is invalid.
69 /// Should PTT be on right now? Polled by external
72 /// TxDelay raw value, number of 10ms units. We will optimistically start with default 0.
75 /// This is a full duplex channel so we do not need to monitor DCD or use CSMA. Default false.
80 pub fn new() -> Self {
82 kiss_buffer
: KissBuffer
::new(),
86 next_csma_check
: None
,
88 packet_queue
: Default
::default(),
92 stream_pending_lsf
: None
,
93 stream_queue
: Default
::default(),
103 /// Process an individual `Frame` that has been decoded by the modem.
104 pub fn handle_frame(&mut self, frame
: Frame
) {
107 // A new LSF implies a clean slate.
108 // If we were partway through decoding something else then we missed it.
111 self.state
= State
::RxPacket(RxPacketState
{
118 let kiss
= KissFrame
::new_stream_setup(&lsf
.0).unwrap
();
119 self.kiss_to_host(kiss
);
120 self.state
= State
::RxStream(RxStreamState
{
127 Frame
::Packet(packet
) => {
128 match &mut self.state
{
129 State
::RxPacket(ref mut rx
) => {
130 match packet
.counter
{
131 PacketFrameCounter
::Frame
{ index
} => {
132 if index
== rx
.count
&& index
< 32 {
133 let start
= 25 * index
;
134 rx
.packet
[start
..(start
+ 25)].copy_from_slice(&packet
.payload
);
137 // unexpected order - something has gone wrong
138 self.state
= State
::Idle
;
141 PacketFrameCounter
::FinalFrame
{ payload_len
} => {
142 let start
= 25 * rx
.count
;
143 let end
= start
+ payload_len
;
144 rx
.packet
[start
..(start
+ payload_len
)]
145 .copy_from_slice(&packet
.payload
[0..payload_len
]);
146 // TODO: compatible packets should be sent on port 0 too
148 KissFrame
::new_full_packet(&rx
.lsf
.0, &rx
.packet
[0..end
])
150 self.kiss_to_host(kiss
);
151 self.state
= State
::Idle
;
156 // Invalid transition
157 self.state
= State
::Idle
;
161 Frame
::Stream(stream
) => {
162 match &mut self.state
{
163 State
::RxStream(ref mut rx
) => {
164 // TODO: consider wraparound from 0x7fff
165 if stream
.frame
_n
umber
< rx
.index
{
166 let mut lich
= LichCollection
::new();
167 lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
168 self.state
= State
::RxAcquiringStream(RxAcquiringStreamState
{ lich
});
170 rx
.index
= stream
.frame
_n
umber
+ 1;
171 let kiss
= KissFrame
::new_stream_data(&stream
).unwrap
();
172 self.kiss_to_host(kiss
);
173 // TODO: end stream if LICH updates indicate non-META part has changed
174 // (this implies a new station)
175 if stream
.end_of_stream
{
176 self.state
= State
::Idle
;
180 State
::RxAcquiringStream(ref mut rx
) => {
181 rx
.lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
182 if let Some(maybe_lsf
) = rx
.lich
.try_assemble() {
183 let lsf
= LsfFrame(maybe_lsf
);
184 // LICH can change mid-transmission so wait until the CRC is correct
185 // to ensure (to high probability) we haven't done a "torn read"
186 if lsf
.check_crc() == 0 {
187 let kiss
= KissFrame
::new_stream_setup(&lsf
.0).unwrap
();
188 self.kiss_to_host(kiss
);
189 // TODO: avoid discarding the first data payload here
190 // need a queue depth of 2 for outgoing kiss
191 self.state
= State
::RxStream(RxStreamState
{
193 index
: stream
.frame
_n
umber
+ 1,
199 // If coming from another state, we have missed something.
200 // Never mind, let's start tracking LICH.
201 let mut lich
= LichCollection
::new();
202 lich
.set_segment(stream
.lich_idx
, stream
.lich_part
);
203 self.state
= State
::RxAcquiringStream(RxAcquiringStreamState
{ lich
})
210 pub fn set_data_carrier_detect(&mut self, dcd
: bool
) {
214 pub fn set_now(&mut self, now_samples
: u64) {
215 self.now
= now_samples
;
217 State
::TxEndingAtTime(time
) => {
218 if now_samples
>= time
{
220 self.state
= State
::Idle
;
227 pub fn ptt(&self) -> bool
{
231 pub fn set_tx_end_time(&mut self, in_samples
: usize) {
232 log
::debug
!("tnc has been told that tx will complete in {in_samples} samples");
235 self.state
= State
::TxEndingAtTime(self.now
+ in_samples
as u64);
241 pub fn read_tx_frame(&mut self) -> Option
<ModulatorFrame
> {
243 State
::Idle
| State
::RxAcquiringStream(_
) | State
::RxStream(_
) | State
::RxPacket(_
) => {
244 let stream_wants_to_tx
= self.stream_pending_lsf
.is
_some
();
245 let packet_wants_to_tx
= self.packet_full
|| (self.packet_next
!= self.packet_curr
);
246 if !stream_wants_to_tx
&& !packet_wants_to_tx
{
250 // We have something we might send if the channel is free
252 // TODO: Proper full duplex support
253 // A true full duplex TNC should be able to rx and tx concurrently, implying
255 if !self.full
_d
uplex
{
256 match self.next_csma_check
{
259 self.next_csma_check
= Some(self.now
+ 1920);
262 // channel is idle at the moment we get a frame to send
267 if self.now
< at_time
{
270 // 25% chance that we'll transmit this slot.
271 // Using self.now as random is probably fine so long as it's not being set in
272 // a lumpy manner. m17app's soundmodem should be fine.
273 // TODO: bring in prng to help in cases where `now` never ends in 0b11
274 let p1_4
= (self.now
& 3) == 3;
275 if !self.dcd
|| !p1_4
{
276 self.next_csma_check
= Some(self.now
+ 1920);
279 self.next_csma_check
= None
;
285 if stream_wants_to_tx
{
286 self.state
= State
::TxStream
;
288 self.state
= State
::TxPacket
;
291 Some(ModulatorFrame
::Preamble
{
292 tx_delay
: self.tx_delay
,
296 if !self.stream_full
&& self.stream_next
== self.stream_curr
{
299 if let Some(lsf
) = self.stream_pending_lsf
.take() {
300 return Some(ModulatorFrame
::Lsf(lsf
));
302 let frame
= self.stream_queue
[self.stream_curr
].clone();
303 if self.stream_full
{
304 self.stream_full
= false;
306 self.stream_curr
= (self.stream_curr
+ 1) % 8;
307 if frame
.end_of_stream
{
308 self.state
= State
::TxStreamSentEndOfStream
;
310 Some(ModulatorFrame
::Stream(frame
))
312 State
::TxStreamSentEndOfStream
=> {
313 self.state
= State
::TxEnding
;
314 Some(ModulatorFrame
::EndOfTransmission
)
317 if !self.packet_full
&& self.packet_next
== self.packet_curr
{
320 while self.packet_next
!= self.packet_curr
{
321 match self.packet_queue
[self.packet_curr
].next_frame() {
326 self.packet_curr
= (self.packet_curr
+ 1) % 4;
330 self.state
= State
::TxEnding
;
331 Some(ModulatorFrame
::EndOfTransmission
)
333 State
::TxEnding
| State
::TxEndingAtTime(_
) => {
334 // Once we have signalled EOT we withold any new frames until
335 // the channel fully clears and we are ready to TX again
341 /// Read KISS message to be sent to host.
343 /// After each frame input, this should be consumed in a loop until length 0 is returned.
344 /// This component will never block. Upstream interface can provide blocking `read()` if desired.
345 pub fn read_kiss(&mut self, target_buf
: &mut [u8]) -> usize {
346 match self.outgoing_kiss
.as_mut() {
348 let n
= (outgoing
.kiss_frame
.len
- outgoing
.sent
).min(target_buf
.len());
350 .copy_from_slice(&outgoing
.kiss_frame
.data
[outgoing
.sent
..(outgoing
.sent
+ n
)]);
352 if outgoing
.sent
== outgoing
.kiss_frame
.len
{
353 self.outgoing_kiss
= None
;
361 /// Host sends in some KISS data.
362 pub fn write_kiss(&mut self, buf
: &[u8]) -> usize {
363 let target_buf
= self.kiss_buffer
.buf_remaining();
364 let n
= buf
.len().min(target_buf
.len());
365 target_buf
[0..n
].copy_from_slice(&buf
[0..n
]);
366 self.kiss_buffer
.did_write(n
);
367 while let Some(kiss_frame
) = self.kiss_buffer
.next_frame() {
368 let Ok(port
) = kiss_frame
.port() else {
371 let Ok(command
) = kiss_frame
.command() else {
374 if port
!= PORT_PACKET_BASIC
&& port
!= PORT_PACKET_FULL
&& port
!= PORT_STREAM
{
377 if command
== KissCommand
::TxDelay
{
378 let mut new_delay
= [0u8; 1];
379 if kiss_frame
.decode_payload(&mut new_delay
) == Ok(1) {
380 self.tx_delay
= new_delay
[0];
384 if command
== KissCommand
::FullDuplex
{
385 let mut new_duplex
= [0u8; 1];
386 if kiss_frame
.decode_payload(&mut new_duplex
) == Ok(1) {
387 self.full
_d
uplex
= new_duplex
[0] != 0;
391 if command
!= KissCommand
::DataFrame
{
392 // Not supporting any other settings yet
393 // TODO: allow adjusting P persistence parameter for CSMA
396 if port
== PORT_PACKET_BASIC
{
397 if self.packet_full
{
400 let mut pending
= PendingPacket
::new();
401 pending
.app_data
[0] = 0x00; // RAW
402 let Ok(mut len
) = kiss_frame
.decode_payload(&mut pending
.app_data
[1..]) else {
405 len
+= 1; // for RAW prefix
406 let packet_crc
= crate::crc
::m17_crc(&pending
.app_data
[0..len
]);
407 pending
.app_data
[len
..len
+ 2].copy_from_slice(&packet_crc
.to_be_bytes());
408 pending
.app_data_len
= len
+ 2;
409 pending
.lsf
= Some(LsfFrame
::new_packet(
410 &Address
::Callsign(Callsign(b
"M17RT-PKT".clone())),
413 self.packet_queue
[self.packet_next
] = pending
;
414 self.packet_next
= (self.packet_next
+ 1) % 4;
415 if self.packet_next
== self.packet_curr
{
416 self.packet_full
= true;
418 } else if port
== PORT_PACKET_FULL
{
419 if self.packet_full
{
422 let mut pending
= PendingPacket
::new();
423 let mut payload
= [0u8; 855];
424 let Ok(len
) = kiss_frame
.decode_payload(&mut payload
) else {
430 let mut lsf
= LsfFrame([0u8; 30]);
431 lsf
.0.copy_from_slice(&payload
[0..30]);
432 if lsf
.check_crc() != 0 {
435 pending
.lsf
= Some(lsf
);
436 let app_data_len
= len
- 30;
437 pending
.app_data
[0..app_data_len
].copy_from_slice(&payload
[30..len
]);
438 pending
.app_data_len
= app_data_len
;
439 self.packet_queue
[self.packet_next
] = pending
;
440 self.packet_next
= (self.packet_next
+ 1) % 4;
441 if self.packet_next
== self.packet_curr
{
442 self.packet_full
= true;
444 } else if port
== PORT_STREAM
{
445 let mut payload
= [0u8; 30];
446 let Ok(len
) = kiss_frame
.decode_payload(&mut payload
) else {
450 log
::debug
!("payload len too short");
454 let lsf
= LsfFrame(payload
);
455 if lsf
.check_crc() != 0 {
458 self.stream_pending_lsf
= Some(lsf
);
460 if self.stream_full
{
461 log
::debug
!("stream full");
464 let frame_num_part
= u16::from_be_bytes([payload
[6], payload
[7]]);
465 self.stream_queue
[self.stream_next
] = StreamFrame
{
466 lich_idx
: payload
[5] >> 5,
467 lich_part
: payload
[0..5].try_into().unwrap
(),
468 frame_number
: frame_num_part
& 0x7fff,
469 end_of_stream
: frame_num_part
& 0x8000 > 0,
470 stream_data
: payload
[8..24].try_into().unwrap
(),
472 self.stream_next
= (self.stream_next
+ 1) % 8;
473 if self.stream_next
== self.stream_curr
{
474 self.stream_full
= true;
482 fn kiss_to_host(&mut self, kiss_frame
: KissFrame
) {
483 self.outgoing_kiss
= Some(OutgoingKiss
{
490 #[derive(Debug, PartialEq, Eq, Clone)]
491 pub enum SoftTncError
{
492 General(&'
static str),
496 struct OutgoingKiss
{
497 kiss_frame
: KissFrame
,
502 /// Nothing happening. We may have TX data queued but we won't act on it until CSMA opens up.
505 /// We received some stream data but missed the leading LSF so we are trying to assemble from LICH.
506 RxAcquiringStream(RxAcquiringStreamState
),
508 /// We have acquired an identified stream transmission and are sending data payloads to the host.
509 RxStream(RxStreamState
),
511 /// We are receiving a packet. All is well so far, and there is more data to come before we tell the host.
512 RxPacket(RxPacketState
),
514 /// PTT is on and this is a stream-type transmission. New data may be added.
517 /// We have delivered the last frame in the current stream
518 TxStreamSentEndOfStream
,
520 /// PTT is on and this is a packet-type transmission. New packets may be enqueued.
523 /// We gave modulator an EndOfTransmission. PTT is still on, waiting for modulator to advise end time.
526 /// Ending transmission, PTT remains on, but we know the timestamp at which we should disengage it.
530 struct RxAcquiringStreamState
{
531 /// Partial assembly of LSF by accumulating LICH fields.
532 lich
: LichCollection
,
535 struct RxStreamState
{
536 /// Track identifying information for this transmission so we can tell if it changes.
539 /// Expected next frame number. Allowed to skip values on RX, but not go backwards.
543 struct RxPacketState
{
547 /// Accumulation of packet data that we have received so far.
550 /// Number of payload frames we have received. If we are stably in the RxPacket state,
551 /// this will be between 0 and 32 inclusive.
555 struct PendingPacket
{
556 lsf
: Option
<LsfFrame
>,
560 app_data_transmitted
: usize,
567 app_data
: [0u8; 825],
569 app_data_transmitted
: 0,
573 /// Returns next frame, not including preamble or EOT.
575 /// False means all data frames have been sent.
576 fn next_frame(&mut self) -> Option
<ModulatorFrame
> {
577 if let Some(lsf
) = self.lsf
.take() {
578 return Some(ModulatorFrame
::Lsf(lsf
));
580 if self.app_data_len
== self.app_data_transmitted
{
583 let remaining
= self.app_data_len
- self.app_data_transmitted
;
584 let (counter
, data_len
) = if remaining
<= 25 {
586 PacketFrameCounter
::FinalFrame
{
587 payload_len
: remaining
,
593 PacketFrameCounter
::Frame
{
594 index
: self.app_data_transmitted
/ 25,
599 let mut payload
= [0u8; 25];
600 payload
[0..data_len
].copy_from_slice(
601 &self.app_data
[self.app_data_transmitted
..(self.app_data_transmitted
+ data_len
)],
603 self.app_data_transmitted
+= data_len
;
604 Some(ModulatorFrame
::Packet(PacketFrame
{ payload
, counter
}))
608 impl Default
for PendingPacket
{
609 fn default() -> Self {
612 app_data
: [0u8; 825],
614 app_data_transmitted
: 0,
622 use crate::kiss
::{KissCommand
, PORT_STREAM
};
623 use crate::protocol
::StreamFrame
;
625 // TODO: finish all handle_frame tests as below
626 // this will be much more straightforward when we have a way to create LSFs programatically
628 // receiving a single-frame packet
630 // receiving a multi-frame packet
632 // part of one packet and then another
635 fn tnc_receive_stream() {
637 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0,
638 0, 0, 0, 0, 0, 131, 53,
640 let stream1
= StreamFrame
{
642 lich_part
: [255, 255, 255, 255, 255],
644 end_of_stream
: false,
646 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
649 let stream2
= StreamFrame
{
651 lich_part
: [255, 0, 0, 0, 159],
655 17, 0, 94, 82, 216, 135, 181, 15, 30, 0, 125, 195, 152, 183, 41, 57,
658 let mut tnc
= SoftTnc
::new();
659 let mut kiss
= KissFrame
::new_empty();
660 assert_eq
!(tnc
.read_kiss(&mut kiss
.data
), 0);
662 tnc
.handle_frame(Frame
::Lsf(lsf
));
663 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
664 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
665 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
667 let mut payload_buf
= [0u8; 2048];
668 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
671 tnc
.handle_frame(Frame
::Stream(stream1
));
672 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
673 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
674 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
676 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
679 tnc
.handle_frame(Frame
::Stream(stream2
));
680 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
681 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
682 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
684 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
689 fn tnc_acquire_stream() {
693 lich_part
: [255, 255, 255, 255, 255],
695 end_of_stream
: false,
697 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
702 lich_part
: [255, 0, 0, 0, 159],
704 end_of_stream
: false,
706 17, 0, 94, 82, 216, 135, 181, 15, 30, 0, 125, 195, 152, 183, 41, 57,
711 lich_part
: [221, 81, 5, 5, 0],
713 end_of_stream
: false,
715 17, 128, 93, 74, 154, 167, 169, 11, 20, 0, 116, 91, 158, 220, 45, 111,
720 lich_part
: [0, 0, 0, 0, 0],
722 end_of_stream
: false,
724 15, 128, 114, 83, 218, 252, 59, 111, 31, 128, 116, 91, 84, 231, 45, 105,
729 lich_part
: [0, 0, 0, 0, 0],
731 end_of_stream
: false,
733 9, 128, 119, 115, 220, 220, 57, 15, 48, 128, 124, 83, 158, 236, 181, 91,
738 lich_part
: [0, 0, 0, 131, 53],
740 end_of_stream
: false,
742 52, 0, 116, 90, 152, 167, 225, 216, 32, 0, 116, 83, 156, 212, 33, 216,
747 let mut tnc
= SoftTnc
::new();
748 let mut kiss
= KissFrame
::new_empty();
750 tnc
.handle_frame(Frame
::Stream(f
));
752 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
753 let mut payload_buf
= [0u8; 2048];
754 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
759 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0,
760 0, 0, 0, 0, 0, 0, 131, 53,
766 fn tnc_handle_skipped_stream_frame() {
768 255, 255, 255, 255, 255, 255, 0, 0, 0, 159, 221, 81, 5, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0,
769 0, 0, 0, 0, 0, 131, 53,
771 let stream1
= StreamFrame
{
773 lich_part
: [255, 255, 255, 255, 255],
775 end_of_stream
: false,
777 128, 0, 119, 115, 220, 252, 41, 235, 8, 0, 116, 195, 94, 244, 45, 75,
780 let stream3
= StreamFrame
{
782 lich_part
: [221, 81, 5, 5, 0],
784 end_of_stream
: false,
786 17, 128, 93, 74, 154, 167, 169, 11, 20, 0, 116, 91, 158, 220, 45, 111,
789 let mut tnc
= SoftTnc
::new();
790 let mut kiss
= KissFrame
::new_empty();
791 assert_eq
!(tnc
.read_kiss(&mut kiss
.data
), 0);
793 tnc
.handle_frame(Frame
::Lsf(lsf
));
794 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
795 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
796 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
798 let mut payload_buf
= [0u8; 2048];
799 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
802 tnc
.handle_frame(Frame
::Stream(stream1
));
803 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
804 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
805 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
807 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();
810 tnc
.handle_frame(Frame
::Stream(stream3
));
811 kiss
.len
= tnc
.read_kiss(&mut kiss
.data
);
812 assert_eq
!(kiss
.command().unwrap
(), KissCommand
::DataFrame
);
813 assert_eq
!(kiss
.port().unwrap
(), PORT_STREAM
);
815 let n
= kiss
.decode_payload(&mut payload_buf
).unwrap
();