diff --git a/README.md b/README.md index 82e2f8d..085a6ca 100644 --- a/README.md +++ b/README.md @@ -23,5 +23,63 @@ It should be possible to just open the horusbinary_radiolib.ino file in the Ardu Note that I am using some AVR-specific CRC16 libraries (`util/crc16.h`), which will probably need to be replaced for use on other platforms (refer `util.ino`). +## Horus Binary Generation & Transmission Overview + +### Packet Structure +The Horus Binary [packet formats](https://github.com/projecthorus/horusdemodlib/wiki/4-Packet-Format-Details) are represented in this codebase as structs located [here](https://github.com/projecthorus/horusbinary_radiolib/blob/main/horusbinary_radiolib.ino#L45) (v1) and [here](https://github.com/projecthorus/horusbinary_radiolib/blob/main/horusbinary_radiolib.ino#L63) (v2). The last 9 bytes (before the CRC16 checksum) of the v2 packet format are customisable by the user ([refer here](https://github.com/projecthorus/horusdemodlib/wiki/5-Customising-a-Horus-Binary-v2-Packet) for more info). + +### Generating a Packet +The two functions [`build_horus_binary_packet_v1`](https://github.com/projecthorus/horusbinary_radiolib/blob/main/horusbinary_radiolib.ino#L94) and [`build_horus_binary_packet_v2`](https://github.com/projecthorus/horusbinary_radiolib/blob/main/horusbinary_radiolib.ino#L121) instantiate a struct, and write data into it. The struct bytes are then written out to a buffer (in this example, `rawbuffer`) supplied as a function argument, and the function returns the length of the packet in bytes. + +```c +int pkt_len = build_horus_binary_packet_v1(rawbuffer); +``` + +### Encoding the Packet +Next, we need to apply the Golay(23,12) forward-error-correction, interleaving and scrambling which protect the telemetry data. This is performed using the `horus_l2_encode_packet` function, which is located in `horus_l2.cpp`. This function takes a pointer to a destination and source buffer, and the packet length: + +```c +int coded_len = horus_l2_encode_tx_packet((unsigned char*)codedbuffer,(unsigned char*)rawbuffer,pkt_len); +``` + +At this stage we now have the encoded packet in `codedbuffer`, and the length of the encoded packet in `coded_len`. + +### Transmitting the Packet +In this example codebase, we are using RadioLib to provide a nice abstracted interface to a range of radio transmitter modules. In my case I'm using a SX127x-compatible module, which is started as follows: + +```c +// SX1278 has the following connections: +// NSS pin: 10 +// DIO0 pin: 2 +// RESET pin: 9 +// DIO1 pin: 3 +SX1278 radio = new Module(10, 2, 9, 3); +``` + +The radio has to be initialised in FSK mode: +```c +int state = radio.beginFSK(); +``` + +Next, I have provided some functions in `FSK4_Mod.ino` which will make use of the radio modules 'transmitDirect' functionality to transmit the 4FSK modulation. We have to initialise these functions using the fsk4_setup function: + +```c +state = fsk4_setup(&radio, TX_FREQ, FSK4_SPACING, FSK4_BAUD); +``` +`TX_FREQ` is the frequency of the lowest 4FSK tone in MHz, `FSK4_BAUD` is the desired baud rate (recommended to be 100 baud, though 50 and 300 baud are supported in the decoders), and `FSK4_SPACING` is the spacing between the tones in Hz (should be >=2x the baud rate). + +Note that the *acheived* tone spacing depends on the frequency resolution of the radio module. In the case of the SX127x the resolution is 61 Hz, so while I specify a 270 Hz tone spacing, we end up with an acheived tone spacing of 244 Hz. + +Once we have our encoded packet, we can transmit as follows: +```c +fsk4_idle(&radio); +delay(1000); +fsk4_preamble(&radio, 8); +fsk4_write(&radio, codedbuffer, coded_len); +``` + +`fsk4_idle` turns the transmitter on, and configures it to transmit a carrier on the lowest 4FSK tone. `fsk4_preamble` sends a repeated sequence of incrementing 4FSK tones, allowing the decoder to lock-on to the signal. Finally, `fsk4_write` transmits the encoded payload, and turns the transmitter off once done. + + ## TODO List * Split out Horus-specific code into separate files, for easier integration into other codebases. \ No newline at end of file