Skip to content

Commit 465f14e

Browse files
joergschultzelutterjoergschultzelutter
committed
Updated documentation
1 parent 61d29a5 commit 465f14e

File tree

2 files changed

+10
-216
lines changed

2 files changed

+10
-216
lines changed

‎README.md‎

Lines changed: 9 additions & 215 deletions
Original file line numberDiff line numberDiff line change
@@ -76,230 +76,24 @@ My first test case
7676

7777
- 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.
7878

79-
- 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.
79+
- 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.
8080

8181
- 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.
8282

8383
- The keyword ``Send APRS Packet`` will __not__ check whether the APRS-IS connection has been establised read-only (``N0CALL`` call sign) or read-write.
8484

85-
## Examples
85+
## Robot Framework Library Examples
8686

87-
All examples can be downloaded from this repo.
87+
In order to run these scripts, you need to change them and add your call sign to the script's configuration section:
8888

89-
### Send a single packet to APRS-IS and wait for the response
89+
# This is your APRS-IS call sign. Replace this place holder with your personal call sign
90+
${callsign} YOURCALLSIGN
9091

91-
```robotframework
92-
# Send a single message to WXBOT, wait for a response message and display it on the console.
93-
# Then terminate the test.
94-
#
95-
# Author: Joerg Schultze-Lutter, DF1JSL
96-
# https://www.github.com/joergschultzelutter/robotframework-aprslib
97-
98-
*** Settings ***
99-
Library AprsLibrary.py
100-
101-
Suite Setup Open APRS-IS Connection
102-
Suite Teardown Close APRS-IS Connection
103-
104-
*** Variables ***
105-
106-
# This is your APRS-IS call sign. Replace this place holder with your personal call sign
107-
${callsign} YOURCALLSIGN
108-
109-
# This is the message that we will send out to WXBOT
110-
${message} ${callsign}>APRS::WXBOT${SPACE}${SPACE}${SPACE}${SPACE}:tomorrow
111-
112-
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
113-
${filter} g/WXBOT/${callsign}*
114-
115-
*** Test Cases ***
116-
Send packet to APRS-IS with callsign ${callsign}
117-
Log Send Packet to APRS-IS
118-
Send APRS Packet ${message}
119-
120-
Receive packet from APRS-IS with callsign ${callsign}
121-
Log Receive Packet from APRS-IS
122-
${packet} = Receive APRS Packet
123-
Log To Console ${packet}
124-
125-
*** Keywords ***
126-
Open APRS-IS Connection
127-
${passcode}= Calculate APRS-IS Passcode ${callsign}
128-
129-
Set APRS-IS Callsign ${callsign}
130-
Set APRS-IS Passcode ${passcode}
131-
Set APRS-IS Filter ${filter}
132-
133-
Log Connecting to APRS-IS
134-
Connect to APRS-IS
135-
136-
Close APRS-IS Connection
137-
Log Disconnect from APRS-IS
138-
Disconnect from APRS-IS
139-
```
140-
141-
### Capture 10 APRS messages and display them in raw format
142-
143-
```robotframework
144-
# This is a simple robot which captures up to 10 APRS 'message' type messages and
145-
# logs their raw messages to the console. Then terminate the test
146-
# Author: Joerg Schultze-Lutter, DF1JSL
147-
# https://www.github.com/joergschultzelutter/robotframework-aprslib
148-
149-
*** Settings ***
150-
Library AprsLibrary.py
151-
152-
Suite Setup Open APRS-IS Connection
153-
Suite Teardown Close APRS-IS Connection
154-
155-
*** Variables ***
156-
# This is your APRS-IS call sign. Replace this value with your personal call sign
157-
${callsign} YOURCALLSIGN
158-
159-
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
160-
${filter} t/m
161-
162-
*** Test Cases ***
163-
Echo APRS-IS Raw Traffic to Console
164-
[Documentation] Capture up to 10 APRS messages and display them on the console
165-
166-
# Robot has no WHILE loop. Therefore, we need to use a FOR loop.
167-
FOR ${i} IN RANGE 10
168-
Receive Packet From APRS-IS
169-
END
170-
171-
*** Keywords ***
172-
Open APRS-IS Connection
173-
${passcode}= Calculate APRS-IS Passcode ${callsign}
174-
175-
Set APRS-IS Callsign ${callsign}
176-
Set APRS-IS Passcode ${passcode}
177-
Set APRS-IS Filter ${filter}
178-
179-
Log Connecting to APRS-IS
180-
Connect to APRS-IS
92+
Replace the current placeholder with your call sign and you are good to go.
18193

182-
Close APRS-IS Connection
183-
Log Disconnect from APRS-IS
184-
Disconnect from APRS-IS
185-
186-
Receive packet from APRS-IS
187-
# Receive the package. By default, aprslib decodes it ...
188-
${packet} = Receive APRS Packet
189-
190-
# ... but for now, let's get the raw message from that decode packet
191-
# and display it on the console
192-
${packet} = Get Raw Message Value From APRS Packet ${packet}
193-
Log To Console ${packet}
194-
```
195-
196-
### Receive a message and send an ack plus response to the user
197-
198-
```robotframework
199-
# This is a VERY simplified test which fails if you send unconfirmed
200-
# messages OR messages with the more modern ack/rej schema to it
201-
#
202-
# Author: Joerg Schultze-Lutter, DF1JSL
203-
# https://www.github.com/joergschultzelutter
204-
205-
*** Settings ***
206-
Library AprsLibrary.py
207-
Library String
208-
209-
Suite Setup Open APRS-IS Connection
210-
Suite Teardown Close APRS-IS Connection
211-
212-
*** Variables ***
213-
214-
# This is your APRS-IS call sign. Replace this value with your personal call sign
215-
${callsign} YOURCALLSIGN
216-
217-
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
218-
${filter} g/${callsign}*
219-
220-
*** Test Cases ***
221-
Simple Receive-and-Respond Test Case
222-
[Documentation] Our 'master receiver' task
223-
# The current Robot Framework does not support WHILE loops. This is a still a
224-
# finite loop but as our goal is only to receive a single message, this
225-
# crude approach will do.
226-
Wait Until Keyword Succeeds 50x 0sec Receive Packet From APRS-IS
227-
228-
*** Keywords ***
229-
230-
Receive packet from APRS-IS
231-
[Documentation] VERY simplified ack-and-respond-to-message test case. Sends ack & msg to user, then terminates the test
232-
Log Receive message from APRS-IS
233-
${packet} = Receive APRS Packet
234-
235-
${format_string}= Get Format Value From APRS Packet ${packet}
236-
Run Keyword If '${format_string}' != 'message' Fail msg=Packet format is not 'message'; start new loop
237-
238-
${from_string}= Get From Value From APRS Packet ${packet}
239-
${adresse_string}= Get Adresse Value From APRS Packet ${packet}
240-
${msgtext_string}= Get Message Text Value From APRS Packet ${packet}
241-
242-
# The msgno might not be present for unconfirmed messsages. A failure to extract the msgno
243-
# simply triggers a new WUKS loop. After all, this is a VERY very simplified library demo.
244-
#
245-
# Therefore, I don't care about this case and simply expect to receive a message with a
246-
# msgno present. Additionally, keep in mind that alphanumeric message number qualifiers
247-
# are currently not parsed by the aprslib library.
248-
${msgno_string}= Get Message Number Value From APRS Packet ${packet}
249-
250-
# If we have received an ack or a rej, we simply ignore the message and start anew
251-
Run Keyword If '${msgtext_string}' == 'ack' Fail msg=Ignoring ack, start new loop
252-
Run Keyword If '${msgtext_string}' == 'rej' Fail msg=Ignoring rej, start new loop
253-
254-
# show the user what we have received
255-
Log To Console I have received '${msgtext_string}'
256-
257-
# Send the ack
258-
# build the ack based on the incoming message number
259-
${ackmsg} = Format String {}>APRS::{:9}:ack{} ${adresse_string} ${from_string} ${msgno_string}
260-
# and send the ack to APRS-IS
261-
Log To Console Sending acknowledgement '${ackmsg}'
262-
Send Packet to APRS-IS ${ackmsg}
263-
264-
# do not flood the APRS-IS network
265-
Sleep 2sec
266-
267-
# Send the actual message
268-
# Get a message number from the library
269-
${mymsgno}= Get APRS MsgNo As Alphanumeric Value
270-
# Increment the library's message number (not really necessary here as we only deal with one message)
271-
Increment APRS MsgNo
272-
# build the final string
273-
${msg}= Format String {}>APRS::{:9}:{} {}{} ${adresse_string} ${from_string} Hello ${from_string} , your Robot Overlords send greetings!
274-
${msg}= Catenate SEPARATOR= ${msg} { ${mymsgno}
275-
# and send the message to APRS-IS
276-
Log To Console Sending actual message '${msg}'
277-
Send Packet to APRS-IS ${msg}
278-
279-
Log To Console And we're done
280-
281-
Send Packet to APRS-IS
282-
[Documentation] Send packet to APRS-IS
283-
[arguments] ${message}
284-
Log Send Packet to APRS-IS
285-
Send APRS Packet ${message}
286-
287-
Open APRS-IS Connection
288-
[Documentation] Establishes a connection to APRS-IS
289-
${passcode}= Calculate APRS-IS Passcode ${callsign}
290-
291-
Set APRS-IS Callsign ${callsign}
292-
Set APRS-IS Passcode ${passcode}
293-
Set APRS-IS Filter ${filter}
294-
295-
Log Connecting to APRS-IS
296-
Connect to APRS-IS
297-
298-
Close APRS-IS Connection
299-
[Documentation] Closes an existing connection to APRS-IS
300-
Log Disconnect from APRS-IS
301-
Disconnect from APRS-IS
302-
```
94+
- [Echo incoming APRS messages](src/echo_aprsis_traffic.robot)
95+
- [Send and receive a single APRS message](src/send_and_receive_single_packet.robot)
96+
- [Receive a message, acknowledge it if necessary and then respond to it](src/receive_and_send_single_packet.robot)
30397

30498
## The fine print
30599

‎src/AprsLibrary.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
)
3131
logger = logging.getLogger(__name__)
3232

33-
__version__ = "0.4.0"
33+
__version__ = "0.4.1"
3434
__author__ = "Joerg Schultze-Lutter"
3535

3636

0 commit comments

Comments
 (0)