R Bernard Davison > Device-TNC-0.03 > Device::TNC::KISS

Download:
Device-TNC-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

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::SerialPort

http://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.

syntax highlighting: