From 7d3833470e8e34f77f395f02d36429b03469eb18 Mon Sep 17 00:00:00 2001
From: Thomas Beierlein <dl1jbe@darc.de>
Date: Thu, 24 Oct 2024 21:46:04 +0200
Subject: [PATCH] Document lan messages (#448)

* document used LAN message ID's and format of the messages
---
 src/lancode.h | 69 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 11 deletions(-)

diff --git a/src/lancode.h b/src/lancode.h
index c9114ccb..94774f44 100644
--- a/src/lancode.h
+++ b/src/lancode.h
@@ -17,22 +17,69 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  */
 
-
 #ifndef LANCODE_H
 #define LANCODE_H
 
 #define MAXNODES 8
 
-#define LOGENTRY '1'
-#define CLUSTERMSG '2'
-#define TLFSPOT '3'
-#define TLFMSG '4'
-#define FREQMSG '5'
-#define INCQSONUM '6'
-#define TIMESYNC '7'
-#define QTCRENTRY '8'
-#define QTCSENTRY '9'
-#define QTCFLAG ':'
+/* TLF can communicate with other TLF instances to form a net of distributed
+ * logging stations. For that purpose it sends broadcast messages about
+ * relevant events to other TLF nodes.
+ * The following message types are supported:
+ */
+
+#define LOGENTRY '1'	// just logged QSO at that station
+#define CLUSTERMSG '2'	// received messages from DX-cluster
+#define TLFSPOT '3'	// DX-spot generated by operator itself
+#define TLFMSG '4'	// Talk message for local chat
+#define FREQMSG '5'	// actual QRG
+#define INCQSONUM '6'	// last QSO nr used for serial exchange by node
+#define TIMESYNC '7'	// actual time (if TIME_MASTER node)
+#define QTCRENTRY '8'	// received QTC
+#define QTCSENTRY '9'	// sent QTC
+#define QTCFLAG ':'	// QTC flags
+
+/* Each sent message is sent as UDP packet and consists of
+ * - 1 character for the sending node ID, followed by
+ * - 1 character for the above defined message ID, followed by
+ * - a message specific string of characters as body
+ */
+
+/* The format of the message specific string is as follows:
+ *
+ * LOGENTRY
+ * 	Standard logline with LOGLINELEN characters (last one is \n)
+ * CLUSTERMSG
+ *	max 78 characters from DX-cluster,
+ *	followed by \n
+ * TLFSPOT
+ *	77 characters self formatted cluster message,
+ *	e.g.
+ * 'DX de TLF-B:        21.435  K3NBD                                     1041Z'
+ *	followed by \n\n
+ * TLFMSG
+ * 	Max 60 characters text (see talk()) followed by \n
+ * FREQMSG
+ *	7 characters actual QRG in kHz with one decimal,
+ *	left padded with spaces if with TRXcontrol
+ *	7 characters band in meters with one decimal if without TRXcontrol
+ *	followed by \n in both cases
+ * INCQSONR
+ *	QSO number with max. 4 digits,
+ *	followed by \n
+ * TIMESYNC
+ * 	actual time_t value as decimal number,
+ * 	followed by one space
+ *  QTCRENTRY
+ *	QTC logline for RECV direction,
+ *	followed by \n\n
+ *  QTCSENTRY
+ *	QTC logline for SEND direction,
+ *	followed by \n\n
+ *  QTCFLAG
+ *	'<callsign>;L' or '<callsign;N,'
+ *	followed by \n\n
+ */
 
 #include <hamlib/rig.h>