From 465f14e68adcd0e8ee3d7469a6cb826d04a009d6 Mon Sep 17 00:00:00 2001 From: Joerg Schultze-Lutter Date: Sat, 6 Nov 2021 22:14:22 +0100 Subject: [PATCH] Updated documentation --- README.md | 224 ++------------------------------------------- src/AprsLibrary.py | 2 +- 2 files changed, 10 insertions(+), 216 deletions(-) diff --git a/README.md b/README.md index de08962..0b64589 100644 --- a/README.md +++ b/README.md @@ -76,230 +76,24 @@ My first test case - Apart from minor helper methods for the connection setup and field check/retrieval, this Robot Framework library does not offer any additional keywords for exchanging data in a proper way. (Almost) every feature that the original [aprslib](https://github.com/rossengeorgiev/aprs-python) offers is supported by this Robot library - nothing more and nothing less. As aprslib does not [support the more recent replyack scheme](http://www.aprs.org/aprs11/replyacks.txt), this keyword library will also not decode these messages in a proper way and you may need to decode them manually. I was thinking about introducing a workaround to this library (the one that [mpad](https://github.com/joergschultzelutter/mpad) uses), but in the end this decoding should rather be done by aprslib itself. -- The current version of the Robot Framework does not support WHILE loops which would permit the Robot script to run endlessly (when needed). Loops can only be triggered with the help of finite FOR loops. This should be enough for testing but unless a real WHILE loop is made available for the Robot Framework, you can't build an APRS messaging server which will not terminate after a certain point in time. +- The current version of the Robot Framework does not support WHILE loops (planned for RF 5.x) which would permit the Robot script to run endlessly (when needed). Loops can only be triggered with the help of finite FOR loops. This should be enough for testing but unless a real WHILE loop is made available for the Robot Framework, you can't build an APRS messaging server which will not terminate after a certain point in time. - The ```Receive APRS Packet``` keyword has no timeout which means that it will only return back from this code if it has found a message that is to be returned back to Robot. If you depend on timeout, you may need to amend your APRS-IS filter settings and handle the filter process in your code. - The keyword ``Send APRS Packet`` will __not__ check whether the APRS-IS connection has been establised read-only (``N0CALL`` call sign) or read-write. -## Examples +## Robot Framework Library Examples -All examples can be downloaded from this repo. +In order to run these scripts, you need to change them and add your call sign to the script's configuration section: -### Send a single packet to APRS-IS and wait for the response + # This is your APRS-IS call sign. Replace this place holder with your personal call sign + ${callsign} YOURCALLSIGN -```robotframework -# Send a single message to WXBOT, wait for a response message and display it on the console. -# Then terminate the test. -# -# Author: Joerg Schultze-Lutter, DF1JSL -# https://www.github.com/joergschultzelutter/robotframework-aprslib - -*** Settings *** -Library AprsLibrary.py - -Suite Setup Open APRS-IS Connection -Suite Teardown Close APRS-IS Connection - -*** Variables *** - -# This is your APRS-IS call sign. Replace this place holder with your personal call sign -${callsign} YOURCALLSIGN - -# This is the message that we will send out to WXBOT -${message} ${callsign}>APRS::WXBOT${SPACE}${SPACE}${SPACE}${SPACE}:tomorrow - -# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx -${filter} g/WXBOT/${callsign}* - -*** Test Cases *** -Send packet to APRS-IS with callsign ${callsign} - Log Send Packet to APRS-IS - Send APRS Packet ${message} - -Receive packet from APRS-IS with callsign ${callsign} - Log Receive Packet from APRS-IS - ${packet} = Receive APRS Packet - Log To Console ${packet} - -*** Keywords *** -Open APRS-IS Connection - ${passcode}= Calculate APRS-IS Passcode ${callsign} - - Set APRS-IS Callsign ${callsign} - Set APRS-IS Passcode ${passcode} - Set APRS-IS Filter ${filter} - - Log Connecting to APRS-IS - Connect to APRS-IS - -Close APRS-IS Connection - Log Disconnect from APRS-IS - Disconnect from APRS-IS -``` - -### Capture 10 APRS messages and display them in raw format - -```robotframework -# This is a simple robot which captures up to 10 APRS 'message' type messages and -# logs their raw messages to the console. Then terminate the test -# Author: Joerg Schultze-Lutter, DF1JSL -# https://www.github.com/joergschultzelutter/robotframework-aprslib - -*** Settings *** -Library AprsLibrary.py - -Suite Setup Open APRS-IS Connection -Suite Teardown Close APRS-IS Connection - -*** Variables *** -# This is your APRS-IS call sign. Replace this value with your personal call sign -${callsign} YOURCALLSIGN - -# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx -${filter} t/m - -*** Test Cases *** -Echo APRS-IS Raw Traffic to Console - [Documentation] Capture up to 10 APRS messages and display them on the console - - # Robot has no WHILE loop. Therefore, we need to use a FOR loop. - FOR ${i} IN RANGE 10 - Receive Packet From APRS-IS - END - -*** Keywords *** -Open APRS-IS Connection - ${passcode}= Calculate APRS-IS Passcode ${callsign} - - Set APRS-IS Callsign ${callsign} - Set APRS-IS Passcode ${passcode} - Set APRS-IS Filter ${filter} - - Log Connecting to APRS-IS - Connect to APRS-IS +Replace the current placeholder with your call sign and you are good to go. -Close APRS-IS Connection - Log Disconnect from APRS-IS - Disconnect from APRS-IS - -Receive packet from APRS-IS - # Receive the package. By default, aprslib decodes it ... - ${packet} = Receive APRS Packet - - # ... but for now, let's get the raw message from that decode packet - # and display it on the console - ${packet} = Get Raw Message Value From APRS Packet ${packet} - Log To Console ${packet} -``` - -### Receive a message and send an ack plus response to the user - -```robotframework -# This is a VERY simplified test which fails if you send unconfirmed -# messages OR messages with the more modern ack/rej schema to it -# -# Author: Joerg Schultze-Lutter, DF1JSL -# https://www.github.com/joergschultzelutter - -*** Settings *** -Library AprsLibrary.py -Library String - -Suite Setup Open APRS-IS Connection -Suite Teardown Close APRS-IS Connection - -*** Variables *** - -# This is your APRS-IS call sign. Replace this value with your personal call sign -${callsign} YOURCALLSIGN - -# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx -${filter} g/${callsign}* - -*** Test Cases *** -Simple Receive-and-Respond Test Case - [Documentation] Our 'master receiver' task - # The current Robot Framework does not support WHILE loops. This is a still a - # finite loop but as our goal is only to receive a single message, this - # crude approach will do. - Wait Until Keyword Succeeds 50x 0sec Receive Packet From APRS-IS - -*** Keywords *** - -Receive packet from APRS-IS - [Documentation] VERY simplified ack-and-respond-to-message test case. Sends ack & msg to user, then terminates the test - Log Receive message from APRS-IS - ${packet} = Receive APRS Packet - - ${format_string}= Get Format Value From APRS Packet ${packet} - Run Keyword If '${format_string}' != 'message' Fail msg=Packet format is not 'message'; start new loop - - ${from_string}= Get From Value From APRS Packet ${packet} - ${adresse_string}= Get Adresse Value From APRS Packet ${packet} - ${msgtext_string}= Get Message Text Value From APRS Packet ${packet} - - # The msgno might not be present for unconfirmed messsages. A failure to extract the msgno - # simply triggers a new WUKS loop. After all, this is a VERY very simplified library demo. - # - # Therefore, I don't care about this case and simply expect to receive a message with a - # msgno present. Additionally, keep in mind that alphanumeric message number qualifiers - # are currently not parsed by the aprslib library. - ${msgno_string}= Get Message Number Value From APRS Packet ${packet} - - # If we have received an ack or a rej, we simply ignore the message and start anew - Run Keyword If '${msgtext_string}' == 'ack' Fail msg=Ignoring ack, start new loop - Run Keyword If '${msgtext_string}' == 'rej' Fail msg=Ignoring rej, start new loop - - # show the user what we have received - Log To Console I have received '${msgtext_string}' - - # Send the ack - # build the ack based on the incoming message number - ${ackmsg} = Format String {}>APRS::{:9}:ack{} ${adresse_string} ${from_string} ${msgno_string} - # and send the ack to APRS-IS - Log To Console Sending acknowledgement '${ackmsg}' - Send Packet to APRS-IS ${ackmsg} - - # do not flood the APRS-IS network - Sleep 2sec - - # Send the actual message - # Get a message number from the library - ${mymsgno}= Get APRS MsgNo As Alphanumeric Value - # Increment the library's message number (not really necessary here as we only deal with one message) - Increment APRS MsgNo - # build the final string - ${msg}= Format String {}>APRS::{:9}:{} {}{} ${adresse_string} ${from_string} Hello ${from_string} , your Robot Overlords send greetings! - ${msg}= Catenate SEPARATOR= ${msg} { ${mymsgno} - # and send the message to APRS-IS - Log To Console Sending actual message '${msg}' - Send Packet to APRS-IS ${msg} - - Log To Console And we're done - -Send Packet to APRS-IS - [Documentation] Send packet to APRS-IS - [arguments] ${message} - Log Send Packet to APRS-IS - Send APRS Packet ${message} - -Open APRS-IS Connection - [Documentation] Establishes a connection to APRS-IS - ${passcode}= Calculate APRS-IS Passcode ${callsign} - - Set APRS-IS Callsign ${callsign} - Set APRS-IS Passcode ${passcode} - Set APRS-IS Filter ${filter} - - Log Connecting to APRS-IS - Connect to APRS-IS - -Close APRS-IS Connection - [Documentation] Closes an existing connection to APRS-IS - Log Disconnect from APRS-IS - Disconnect from APRS-IS -``` +- [Echo incoming APRS messages](src/echo_aprsis_traffic.robot) +- [Send and receive a single APRS message](src/send_and_receive_single_packet.robot) +- [Receive a message, acknowledge it if necessary and then respond to it](src/receive_and_send_single_packet.robot) ## The fine print diff --git a/src/AprsLibrary.py b/src/AprsLibrary.py index 94edb64..4caf3f3 100644 --- a/src/AprsLibrary.py +++ b/src/AprsLibrary.py @@ -30,7 +30,7 @@ ) logger = logging.getLogger(__name__) -__version__ = "0.4.0" +__version__ = "0.4.1" __author__ = "Joerg Schultze-Lutter"