NAME
Device::TNC::KISS - Device::TNC subclass interface to a KISS mode TNC
DESCRIPTION
This module trys to implement an easy way to talk to a KISS mode Terminal Node Controller (TNC) such as the TNC-X via a serial port.
SYNOPSIS
use Device::TNC::KISS;
To read data direct from a TNC:
my %tnc_config = (
'port' => ($Config{'osname'} eq "MSWin32") ? "COM3" : "/dev/TNC-X",
'baudrate' => 9600,
'warn_malformed_kiss' => 1,
'raw_log' => "raw_packet.log",
);
To read data from a raw KISS log file
my %tnc_config = (
'warn_malformed_kiss' => 1,
'file' => "raw_packet.log",
);
my $kiss_tnc = new Device::TNC::KISS(%tnc_config);
my $kiss_frame = $kiss_tnc->read_kiss_frame();
my @kiss_frame = $kiss_tnc->read_kiss_frame();
my ($kiss_type, $hdlc_frame) = $kiss_tnc->read_hdlc_frame();
my ($kiss_type, @hdlc_frame) = $kiss_tnc->read_hdlc_frame();This module was developed on Linux and Windows. It should work for any UNIX like operating system where the Device::SerialPort module can be used.
new()
my %port_data = { 'option' => 'value' };
my $kiss_tnc = new Device::TNC::KISS(%port_data);The new method creates and returns a new Device::TNC::KISS object that can be used to communicate with a KISS mode terminal node controller.
The method requires that a hash of settings be passed. If the port and baudrate are not set in the passed settings or the port cannot be opened an error message is printed and undef returned.
Options and values
- port
-
This sets the serial port name as appropriate for the operating system. For UNIX this will be something like /dev/ttyS0 and for Windows this will be something like COM1
- baudrate
-
The baud rate is the speed the TNC is configured to talk at. i.e. 1200 baud.
- warn_malformed_kiss
-
To see warnings about malformed KISS frames then set this option to a true value
- raw_log
-
If you want to keep a log of the raw packets that are read then set raw_log to the name of the log file you which to write to. If there is an error opening the log file the
- file
-
Use to read KISS frames from a file instead of a port. Using this option will cause the module to ignore any port, baudrate and raw_log options.
The value for this option should be a raw KISS log file such as that created via the raw_log option.
The returned object contains a reference to a serial port object which is either a Device::SerialPort (UNIX) or Win32::SerialPort (Windows) object.
The serial port is initialised will the following
$kiss_tnc->{'PORT'}->parity("none");
$kiss_tnc->{'PORT'}->databits(8);
$kiss_tnc->{'PORT'}->stopbits(1);
$kiss_tnc->{'PORT'}->handshake("none");
$kiss_tnc->{'PORT'}->read_interval(100) if $Config{'osname'} eq "MSWin32";
$kiss_tnc->{'PORT'}->read_char_time(0);
$kiss_tnc->{'PORT'}->read_const_time(1000);For more details on this see the documentation for Device::SerialPort (UNIX) or Win32::SerialPort (Windows).
read_kiss_frame()
my $kiss_frame = $kiss_tnc->read_kiss_frame();
my @kiss_frame = $kiss_tnc->read_kiss_frame();This method reads a KISS frame from the TNC and returns it. This has not had the FEND, FESC, TFEND and TFESC bytes stripped out.
read_hdlc_frame()
my ($kiss_type, $hdlc_frame) = $kiss_tnc->read_hdlc_frame();
my ($kiss_type, @hdlc_frame) = $kiss_tnc->read_hdlc_frame();This method reads a KISS frame from the TNC and strips out the KISS FEND, FESC, TFEND and TFESC bytes and returns the KISS type byte followed by the HDLC frame.
The value of type indicator byte is use to distinguish between command and data frames.
From: The KISS TNC: A simple Host-to-TNC communications protocol http://people.qualcomm.com/karn/papers/kiss.html
To distinguish between command and data frames on the host/TNC link, the first byte of each asynchronous frame between host and TNC is a "type" indicator. This type indicator byte is broken into two 4-bit nibbles so that the low-order nibble indicates the command number (given in the table below) and the high-order nibble indicates the port number for that particular command. In systems with only one HDLC port, it is by definition Port 0. In multi-port TNCs, the upper 4 bits of the type indicator byte can specify one of up to sixteen ports. The following commands are defined in frames to the TNC (the "Command" field is in hexadecimal):
Command Function Comments
0 Data frame The rest of the frame is data to
be sent on the HDLC channel.
1 TXDELAY The next byte is the transmitter
keyup delay in 10 ms units.
The default start-up value is 50
(i.e., 500 ms).
2 P The next byte is the persistence
parameter, p, scaled to the range
0 - 255 with the following
formula:
P = p * 256 - 1
The default value is P = 63
(i.e., p = 0.25).
3 SlotTime The next byte is the slot interval
in 10 ms units.
The default is 10 (i.e., 100ms).
4 TXtail The next byte is the time to hold
up the TX after the FCS has been
sent, in 10 ms units. This command
is obsolete, and is included here
only for compatibility with some
existing implementations.
5 FullDuplex The next byte is 0 for half duplex,
nonzero for full duplex.
The default is 0
(i.e., half duplex).
6 SetHardware Specific for each TNC. In the
TNC-1, this command sets the
modem speed. Other implementations
may use this function for other
hardware-specific functions.
FF Return Exit KISS and return control to a
higher-level program. This is useful
only when KISS is incorporated
into the TNC along with other
applications.The following types are defined in frames to the host:
Type Function Comments
0 Data frame Rest of frame is data from
the HDLC channel.No other types are defined; in particular, there is no provision for acknowledging data or command frames sent to the TNC. KISS implementations must ignore any unsupported command types. All KISS implementations must implement commands 0,1,2,3 and 5; the others are optional.
SEE ALSO
Device::SerialPort
Win32::SerialPorthttp://people.qualcomm.com/karn/papers/kiss.html
AUTHOR
R Bernard Davison <bdavison@asri.org.au>
COPYRIGHT
Copyright (C) 2007, Australian Space Research Institute.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.