Skip to content

Commit

Permalink
Updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@joergschultzelutter
joergschultzelutter committed Nov 6, 2021
1 parent 61d29a5 commit 465f14e
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 216 deletions.
224 changes: 9 additions & 215 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/AprsLibrary.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
)
logger = logging.getLogger(__name__)

__version__ = "0.4.0"
__version__ = "0.4.1"
__author__ = "Joerg Schultze-Lutter"


Expand Down

0 comments on commit 465f14e

Please sign in to comment.