firmware: src: ngham: Importing the original NGHam source files #8

spacelab-ufsc · Jan 20, 2021 · ba43bc2 · ba43bc2
1 parent 2eff01d
commit ba43bc2
Show file tree

Hide file tree

Showing 151 changed files with 20,272 additions and 1,933 deletions.
diff --git a/firmware/src/ngham/LICENSE b/firmware/src/ngham/LICENSE
@@ -0,0 +1,166 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+
diff --git a/firmware/src/ngham/README.md b/firmware/src/ngham/README.md
@@ -0,0 +1,74 @@
+NGHam protocol
+==============
+
+NGHam, short for Next Generation Ham Radio, is a set of protocols for packet radio communication. Its usage is similar to the existing AX.25 protocol. The standard covers three sub-protocols:
+- NGHam radio protocol
+- NGHam serial port protocol (comparable with KISS for AX.25)
+- NGHam extensions - a modular extension using the payload for addressing, position, voice, statistics etc.
+
+Main features:
+
+- **Very robust:** Allows decoding with lower SNR compared to 1200 baud AFSK AX.25 due to the use of a sync word with good autocorrelation properties and Reed Solomon FEC over the whole remaining packet.
+- **High throughput:** As the sync word eliminates the need for a long preamble and FEC increases chance of successful packet reception, the throughput will be higher than for 9600 baud AX.25.
+- **Better spectral efficiency:** Significantly better spectral efficiency than 1200 baud AFSK, and somewhat better than 9600 baud G3RUH modulation due to the reduced deviation.
+- **More efficient channel access:** CSMA is the default access method, but TDMA with automatic time-synchronization is being developed and is tested.
+- **Clear distinction between communication layers:** The NGHam radio protocol has no addressing or other higher level information, and can be used without NGHam Extension.
+
+[Youtube video: NGHam demonstration with Owl VHF and TDMA](http://youtu.be/_96td-Y-LLA)
+
+
+![NGHam radio protocol (NGHam RF) block schematic](https://github.com/skagmo/ngham/blob/master/documentation/img/ngham_block_v4.png?raw=true)
+
+![NGHam protocol stack explanation](https://github.com/skagmo/ngham/blob/master/documentation/img/ngham_protocol_stack.png?raw=true)
+
+Content:
+
+| File/folder       | Description |
+|:-----------       |:----------- |
+| documentation/    | More documentation. |
+| fec-3.0.1/        | FEC library by Phil Karn for Reed Solomon. (http://www.ka9q.net/code/fec/) |
+| platform/         | User provided - MUST BE CUSTOMIZED. |
+| ccsds_scrambler.h | Pre-generated array from scrambling polynomial. |
+| crc_ccitt.h       | CRC-code used in NGHam. |
+| ngham.h           | The main NGHam encoder/decoder functions. |
+| ngham_packets.h   | Declarations of the TX/RX packet structs etc. |
+| ngham_paths.h     | User provided - MUST BE CUSTOMIZED. |
+| ngham_spp.h       | Serial port protocol for communication with the host.  |
+
+
+Not finished:
+
+| File/folder       | Description |
+|:-----------       |:----------- |
+| ngham_extension.h        | An extension of the payload field in the NGHam radio protocol (enabled by a flag in the NGHam header).  |
+
+Usage (for NGHam RF protocol):
+
+1. Provide your own sync word correlator and GMSK (de)modulator. 
+2. The demodulator should start outputting data only after sync word is detected.
+3. Build all files in the root except "ngham_spp.c". From the folder "fec-3.0.1", build "decode_rs_char.c", "encode_rs_char.c" and "init_rs_char.c".
+3. "ngham_paths.h" and the code in "platform/" must be customized.
+
+```
+// Initialize Reed Solomon arrays - only do this once!
+ngham_init_arrays();
+
+// Initialize state machine
+ngham_init();
+
+// Send a packet containing the payload "TEST"
+tx_pkt_t p;
+p.pl[0] = 'T';
+p.pl[1] = 'E';
+p.pl[2] = 'S';
+p.pl[3] = 'T';
+p.pl_len = 4;
+p.ngham_flags = 0;
+ngham_encode(&p);
+
+// Receive packet. If a complete packet is received, function ngham_action_handle_packet will be called.
+while (demodulator_data_available()) ngham_decode(get_byte_from_demodulator());
+```
+
+--
+Jon Petter Skagmo, LA3JPA, 2014
diff --git a/firmware/src/ngham/ccsds_scrambler.c b/firmware/src/ngham/ccsds_scrambler.c
@@ -1,82 +1,44 @@
-/*
- * ccsds_scrambler.c
- *
- * Copyright (C) 2014, Jon Petter Skagmo
- * Copyright (C) 2017, Gabriel Mariano Marcelino
- * 
- * This file is part of FloripaSat-TTC
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this program; if not, see <http://www.gnu.org/licenses/>
- * 
- */
-
-/**
- * \brief .
- * 
- * \author Jon Petter Skagmo <[email protected]>
- * \author Gabriel Mariano Marcelino <[email protected]>
- * 
- * \version 1.0-dev
- * 
- * \date 27/04/2017
- * 
- * \addtogroup ccsds_scrambler
- * \{
- */
+//**************************************************************//
+// NGHam protocol - Jon Petter Skagmo, LA3JPA, 2014.            //
+// Licensed under LGPL.                                         //
+//**************************************************************//
 
 #include "ccsds_scrambler.h"
 
 #include <stdint.h>
 
-const uint8_t ccsds_poly[255] = {
-    0xFF, 0x48, 0x0E, 0xC0, 0x9A, 0x0D, 0x70, 0xBC, 0x8E, 0x2C, 0x93, 0xAD, 0xA7,
-    0xB7, 0x46, 0xCE, 0x5A, 0x97, 0x7D, 0xCC, 0x32, 0xA2, 0xBF, 0x3E, 0x0A, 0x10,
-    0xF1, 0x88, 0x94, 0xCD, 0xEA, 0xB1, 0xFE, 0x90, 0x1D, 0x81, 0x34, 0x1A, 0xE1,
-    0x79, 0x1C, 0x59, 0x27, 0x5B, 0x4F, 0x6E, 0x8D, 0x9C, 0xB5, 0x2E, 0xFB, 0x98,
-    0x65, 0x45, 0x7E, 0x7C, 0x14, 0x21, 0xE3, 0x11, 0x29, 0x9B, 0xD5, 0x63, 0xFD,
-    0x20, 0x3B, 0x02, 0x68, 0x35, 0xC2, 0xF2, 0x38, 0xB2, 0x4E, 0xB6, 0x9E, 0xDD,
-    0x1B, 0x39, 0x6A, 0x5D, 0xF7, 0x30, 0xCA, 0x8A, 0xFC, 0xF8, 0x28, 0x43, 0xC6,
-    0x22, 0x53, 0x37, 0xAA, 0xC7, 0xFA, 0x40, 0x76, 0x04, 0xD0, 0x6B, 0x85, 0xE4,
-    0x71, 0x64, 0x9D, 0x6D, 0x3D, 0xBA, 0x36, 0x72, 0xD4, 0xBB, 0xEE, 0x61, 0x95,
-    0x15, 0xF9, 0xF0, 0x50, 0x87, 0x8C, 0x44, 0xA6, 0x6F, 0x55, 0x8F, 0xF4, 0x80,
-    0xEC, 0x09, 0xA0, 0xD7, 0x0B, 0xC8, 0xE2, 0xC9, 0x3A, 0xDA, 0x7B, 0x74, 0x6C,
-    0xE5, 0xA9, 0x77, 0xDC, 0xC3, 0x2A, 0x2B, 0xF3, 0xE0, 0xA1, 0x0F, 0x18, 0x89,
-    0x4C, 0xDE, 0xAB, 0x1F, 0xE9, 0x01, 0xD8, 0x13, 0x41, 0xAE, 0x17, 0x91, 0xC5,
-    0x92, 0x75, 0xB4, 0xF6, 0xE8, 0xD9, 0xCB, 0x52, 0xEF, 0xB9, 0x86, 0x54, 0x57,
-    0xE7, 0xC1, 0x42, 0x1E, 0x31, 0x12, 0x99, 0xBD, 0x56, 0x3F, 0xD2, 0x03, 0xB0,
-    0x26, 0x83, 0x5C, 0x2F, 0x23, 0x8B, 0x24, 0xEB, 0x69, 0xED, 0xD1, 0xB3, 0x96,
-    0xA5, 0xDF, 0x73, 0x0C, 0xA8, 0xAF, 0xCF, 0x82, 0x84, 0x3C, 0x62, 0x25, 0x33,
-    0x7A, 0xAC, 0x7F, 0xA4, 0x07, 0x60, 0x4D, 0x06, 0xB8, 0x5E, 0x47, 0x16, 0x49,
-    0xD6, 0xD3, 0xDB, 0xA3, 0x67, 0x2D, 0x4B, 0xBE, 0xE6, 0x19, 0x51, 0x5F, 0x9F,
-    0x05, 0x08, 0x78, 0xC4, 0x4A, 0x66, 0xF5, 0x58
-};
+// Repeats after 255 bits, but repeats byte-aligning after 255 byte
+const uint8_t ccsds_poly[255] = {0xFF, 0x48, 0x0E, 0xC0, 0x9A, 0x0D, 0x70, 0xBC,
+0x8E, 0x2C, 0x93, 0xAD, 0xA7, 0xB7, 0x46, 0xCE, 0x5A, 0x97, 0x7D, 0xCC, 0x32,
+0xA2, 0xBF, 0x3E, 0x0A, 0x10, 0xF1, 0x88, 0x94, 0xCD, 0xEA, 0xB1, 0xFE, 0x90,
+0x1D, 0x81, 0x34, 0x1A, 0xE1, 0x79, 0x1C, 0x59, 0x27, 0x5B, 0x4F, 0x6E, 0x8D,
+0x9C, 0xB5, 0x2E, 0xFB, 0x98, 0x65, 0x45, 0x7E, 0x7C, 0x14, 0x21, 0xE3, 0x11,
+0x29, 0x9B, 0xD5, 0x63, 0xFD, 0x20, 0x3B, 0x02, 0x68, 0x35, 0xC2, 0xF2, 0x38,
+0xB2, 0x4E, 0xB6, 0x9E, 0xDD, 0x1B, 0x39, 0x6A, 0x5D, 0xF7, 0x30, 0xCA, 0x8A,
+0xFC, 0xF8, 0x28, 0x43, 0xC6, 0x22, 0x53, 0x37, 0xAA, 0xC7, 0xFA, 0x40, 0x76,
+0x04, 0xD0, 0x6B, 0x85, 0xE4, 0x71, 0x64, 0x9D, 0x6D, 0x3D, 0xBA, 0x36, 0x72,
+0xD4, 0xBB, 0xEE, 0x61, 0x95, 0x15, 0xF9, 0xF0, 0x50, 0x87, 0x8C, 0x44, 0xA6,
+0x6F, 0x55, 0x8F, 0xF4, 0x80, 0xEC, 0x09, 0xA0, 0xD7, 0x0B, 0xC8, 0xE2, 0xC9,
+0x3A, 0xDA, 0x7B, 0x74, 0x6C, 0xE5, 0xA9, 0x77, 0xDC, 0xC3, 0x2A, 0x2B, 0xF3,
+0xE0, 0xA1, 0x0F, 0x18, 0x89, 0x4C, 0xDE, 0xAB, 0x1F, 0xE9, 0x01, 0xD8, 0x13,
+0x41, 0xAE, 0x17, 0x91, 0xC5, 0x92, 0x75, 0xB4, 0xF6, 0xE8, 0xD9, 0xCB, 0x52,
+0xEF, 0xB9, 0x86, 0x54, 0x57, 0xE7, 0xC1, 0x42, 0x1E, 0x31, 0x12, 0x99, 0xBD,
+0x56, 0x3F, 0xD2, 0x03, 0xB0, 0x26, 0x83, 0x5C, 0x2F, 0x23, 0x8B, 0x24, 0xEB,
+0x69, 0xED, 0xD1, 0xB3, 0x96, 0xA5, 0xDF, 0x73, 0x0C, 0xA8, 0xAF, 0xCF, 0x82,
+0x84, 0x3C, 0x62, 0x25, 0x33, 0x7A, 0xAC, 0x7F, 0xA4, 0x07, 0x60, 0x4D, 0x06,
+0xB8, 0x5E, 0x47, 0x16, 0x49, 0xD6, 0xD3, 0xDB, 0xA3, 0x67, 0x2D, 0x4B, 0xBE,
+0xE6, 0x19, 0x51, 0x5F, 0x9F, 0x05, 0x08, 0x78, 0xC4, 0x4A, 0x66, 0xF5, 0x58};
 
 uint8_t ccsds_poly_pos;
 
-void ngham_CCSDS_ScramblerInit()
-{
-    ccsds_poly_pos = 0;
+void ccsds_scrambler_init(){
+	ccsds_poly_pos = 0;
 }
 
-uint8_t ngham_CCSDS_ScramblerXor(uint8_t data)
-{
-    if (ccsds_poly_pos == 0xFF)
-    {
-        ccsds_poly_pos = 0;
-    }
-
-    return (data ^ ccsds_poly[ccsds_poly_pos++]);
+// Data should be Xored with the sequence, starting from index zero
+uint8_t ccsds_scrambler_xor(uint8_t data){
+	return (data^ccsds_poly[ccsds_poly_pos++]);
+	if (ccsds_poly_pos == 0xff) ccsds_poly_pos = 0;
 }
 
-//! \} End of ccsds_scrambler implementation group
+