Skip to content

Commit be0a381

Browse files
joergschultzelutterjoergschultzelutter
committed
Renamed keywords & new robot for recv/send
1 parent e9ad349 commit be0a381

File tree

3 files changed

+348
-124
lines changed

3 files changed

+348
-124
lines changed

‎README.md

+237-117
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,7 @@
11
# robotframework-aprslib
22
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
33

4-
```robotframework-aprslib``` is a [Robot Framework](https://www.robotframework.org) keyword collection for the [aprslib](https://github.com/rossengeorgiev/aprs-python) Python library. It allows you to establish a connection to the APRS-IS servers and send/receive/decode APRS requests.
5-
6-
## Examples
7-
8-
### Send a single packet to APRS-IS and wait for the response
9-
10-
# Send a single message to WXBOT, wait for a response message and display it on the console.
11-
# Then terminate the test.
12-
#
13-
# Author: Joerg Schultze-Lutter, DF1JSL
14-
# https://www.github.com/joergschultzelutter/robotframework-aprslib
15-
16-
*** Settings ***
17-
Library AprsLibrary.py
18-
19-
Suite Setup Open APRS-IS Connection
20-
Suite Teardown Close APRS-IS Connection
21-
22-
*** Variables ***
23-
24-
# This is your APRS-IS call sign. Replace this place holder with your personal call sign
25-
${callsign} YOURCALLSIGN
26-
27-
# This is the message that we will send out to WXBOT
28-
${message} ${callsign}>APRS::WXBOT${SPACE}${SPACE}${SPACE}${SPACE}:tomorrow
29-
30-
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
31-
${filter} g/WXBOT/${callsign}*
32-
33-
*** Test Cases ***
34-
Send packet to APRS-IS with callsign ${callsign}
35-
Log Send Packet to APRS-IS
36-
Send APRS Packet ${message}
37-
38-
Receive packet from APRS-IS with callsign ${callsign}
39-
Log Receive Packet from APRS-IS
40-
${packet} = Receive APRS Packet
41-
Log To Console ${packet}
42-
43-
*** Keywords ***
44-
Open APRS-IS Connection
45-
${passcode}= Calculate APRS-IS Passcode ${callsign}
46-
47-
Set APRS-IS Callsign ${callsign}
48-
Set APRS-IS Passcode ${passcode}
49-
Set APRS-IS Filter ${filter}
50-
51-
Log Connecting to APRS-IS
52-
Connect to APRS-IS
53-
54-
Close APRS-IS Connection
55-
Log Disconnect from APRS-IS
56-
Disconnect from APRS-IS
57-
58-
## Capture 10 APRS messages and display them in raw format
59-
60-
# This is a simple robot which captures up to 10 APRS 'message' type messages and
61-
# logs their raw messages to the console. Then terminate the test
62-
# Author: Joerg Schultze-Lutter, DF1JSL
63-
# https://www.github.com/joergschultzelutter/robotframework-aprslib
64-
65-
*** Settings ***
66-
Library AprsLibrary.py
67-
68-
Suite Setup Open APRS-IS Connection
69-
Suite Teardown Close APRS-IS Connection
70-
71-
*** Variables ***
72-
# This is your APRS-IS call sign. Replace this value with your personal call sign
73-
${callsign} YOURCALLSIGN
74-
75-
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
76-
${filter} t/m
77-
78-
*** Test Cases ***
79-
Echo APRS-IS Raw Traffic to Console
80-
[Documentation] Capture up to 10 APRS messages and display them on the console
81-
82-
# Robot has no WHILE loop. Therefore, we need to use a FOR loop.
83-
FOR ${i} IN RANGE 10
84-
Receive Packet From APRS-IS
85-
END
86-
87-
*** Keywords ***
88-
Open APRS-IS Connection
89-
${passcode}= Calculate APRS-IS Passcode ${callsign}
90-
91-
Set APRS-IS Callsign ${callsign}
92-
Set APRS-IS Passcode ${passcode}
93-
Set APRS-IS Filter ${filter}
94-
95-
Log Connecting to APRS-IS
96-
Connect to APRS-IS
97-
98-
Close APRS-IS Connection
99-
Log Disconnect from APRS-IS
100-
Disconnect from APRS-IS
101-
102-
Receive packet from APRS-IS
103-
# Receive the package. By default, aprslib decodes it ...
104-
${packet} = Receive APRS Packet
105-
106-
# ... but for now, let's get the raw message from that decode packet
107-
# and display it on the console
108-
${packet} = Get Raw Message Value From APRS Packet ${packet}
109-
Log To Console ${packet}
4+
```robotframework-aprslib``` is a [Robot Framework](https://www.robotframework.org) keyword collection for the [aprslib](https://github.com/rossengeorgiev/aprs-python) Python library. It allows licensed ham radio operators to establish a connection to the APRS-IS servers and send/receive/decode APRS requests.
1105

1116
## Default settings when creating new APRS-IS connection
1127

@@ -117,7 +12,7 @@ When you initialize an APRS connection without explicitly setting parameters suc
11712
- __callsign__ = ``N0CALL``
11813
- __passcode__ = ``-1``
11914
- __aprs-is filter__ = not set
120-
- __aprsis_msgno__ = ``0`` (this is equal to ``AA`` if you need to get the msgno in alphanumeric format)
15+
- __aprsis_msgno__ = ``0`` (this is equal to ``AA`` if you rather want to use the [more recent replyack scheme](http://www.aprs.org/aprs11/replyacks.txt))
12116

12217
This default set of values will allow you to establish a read-only connection to APRS-IS, assuming that the respective APRS-IS server that you intend to connect with permits such a connection.
12318

@@ -127,21 +22,25 @@ You can either specify all parameters during the initial setup of the library or
12722

12823
### Option 1 - set as position parameters
12924

130-
*** Settings ***
25+
```robotframework
26+
*** Settings ***
13127
132-
Library AprsLibrary.py server_value port_value user_value passcode_value filter_value message_value
28+
Library AprsLibrary.py server_value port_value user_value passcode_value filter_value message_value
13329
134-
*** Test Cases ***
135-
My first test case
30+
*** Test Cases ***
31+
My first test case
32+
```
13633

13734
### Option 2 - set as named parameters
13835

139-
*** Settings ***
36+
```robotframework
37+
*** Settings ***
14038
141-
Library AprsLibrary.py aprsis_server=server_value aprsis_port=port_value aprsis_callsign=user_value aprsis_passcode=passcode_value aprsis_filter=filter_value aprsis_msgno = msgno_value
39+
Library AprsLibrary.py aprsis_server=server_value aprsis_port=port_value aprsis_callsign=user_value aprsis_passcode=passcode_value aprsis_filter=filter_value aprsis_msgno = msgno_value
14240
143-
*** Test Cases ***
144-
My first test case
41+
*** Test Cases ***
42+
My first test case
43+
```
14544

14645
### Option 3 - Use Robot Keywords
14746

@@ -153,7 +52,7 @@ You can either specify all parameters during the initial setup of the library or
15352
|``Set APRS-IS Passcode`` and ``Get APRS-IS Passcode``|Sets/Gets the APRS-IS passcode|
15453
|``Set APRS-IS Filter`` and ``Get APRS-IS Filter``|Sets/Gets the APRS-IS server filter. Note: This keyword performs a (basic) sanity check on the content and will cause an error in case an invalid filter qualifier has been submitted|
15554
|``Get Current APRS-IS Configuration``|Returns a dictionary containing all previously listed parameters and the APRS-IS connection status to the user (basically a collection of all previously mentioned keywords). An AIS object whose value is different to ```None``` indicates an active connection.|
156-
|``Get APRS-IS MsgNo``, ``Set APRS-IS MsgNo``, ``Increment APRS-IS MsgNo`` and ``Get APRS-IS MsgNo as Alphanumeric``| Gets and sets the MsgNo. The ``alphanumeric`` keyword provides the message number in a format which [supports the more recent replyack scheme](http://www.aprs.org/aprs11/replyacks.txt). The following rules apply: a) If you want to set the value directly, a max value of 675 (equals ``ZZ``) is possible b) Setter methods only accept numeric values c) if you use the ``Increment`` keyword, an increment to the value of 675 (``ZZ``) will automatically reset the value to ``AA``.
55+
|``Get APRS MsgNo``, ``Set APRS MsgNo``, ``Increment APRS MsgNo`` and ``Get APRS-IS MsgNo as Alphanumeric``| Gets and sets the MsgNo. The ``alphanumeric`` keyword provides the message number in a format which [supports the more recent replyack scheme](http://www.aprs.org/aprs11/replyacks.txt). The following rules apply: a) If you want to set the value directly, a max value of 675 (equals ``ZZ``) is possible b) Setter methods only accept numeric values c) if you use the ``Increment`` keyword, an increment to the value of 675 (``ZZ``) will automatically reset the value to ``AA``. ``Get APRS MsgNo`` does NOT automatically increment the message number.|
15756

15857
## Other Robot Keywords supported by this library
15958

@@ -178,7 +77,228 @@ You can either specify all parameters during the initial setup of the library or
17877

17978
- 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.
18079

181-
- The ```Receive APRS Packet``` command 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.
80+
- 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.
81+
82+
- The keyword ``Send APRS Packet`` will __not__ check whether the APRS-IS connection has been establised read-only (``N0CALL`` call sign) or read-write.
83+
84+
## Examples
85+
86+
All examples can be downloaded from this repo.
87+
88+
### Send a single packet to APRS-IS and wait for the response
89+
90+
```robotframework
91+
# Send a single message to WXBOT, wait for a response message and display it on the console.
92+
# Then terminate the test.
93+
#
94+
# Author: Joerg Schultze-Lutter, DF1JSL
95+
# https://www.github.com/joergschultzelutter/robotframework-aprslib
96+
97+
*** Settings ***
98+
Library AprsLibrary.py
99+
100+
Suite Setup Open APRS-IS Connection
101+
Suite Teardown Close APRS-IS Connection
102+
103+
*** Variables ***
104+
105+
# This is your APRS-IS call sign. Replace this place holder with your personal call sign
106+
${callsign} YOURCALLSIGN
107+
108+
# This is the message that we will send out to WXBOT
109+
${message} ${callsign}>APRS::WXBOT${SPACE}${SPACE}${SPACE}${SPACE}:tomorrow
110+
111+
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
112+
${filter} g/WXBOT/${callsign}*
113+
114+
*** Test Cases ***
115+
Send packet to APRS-IS with callsign ${callsign}
116+
Log Send Packet to APRS-IS
117+
Send APRS Packet ${message}
118+
119+
Receive packet from APRS-IS with callsign ${callsign}
120+
Log Receive Packet from APRS-IS
121+
${packet} = Receive APRS Packet
122+
Log To Console ${packet}
123+
124+
*** Keywords ***
125+
Open APRS-IS Connection
126+
${passcode}= Calculate APRS-IS Passcode ${callsign}
127+
128+
Set APRS-IS Callsign ${callsign}
129+
Set APRS-IS Passcode ${passcode}
130+
Set APRS-IS Filter ${filter}
131+
132+
Log Connecting to APRS-IS
133+
Connect to APRS-IS
134+
135+
Close APRS-IS Connection
136+
Log Disconnect from APRS-IS
137+
Disconnect from APRS-IS
138+
```
139+
140+
### Capture 10 APRS messages and display them in raw format
141+
142+
```robotframework
143+
# This is a simple robot which captures up to 10 APRS 'message' type messages and
144+
# logs their raw messages to the console. Then terminate the test
145+
# Author: Joerg Schultze-Lutter, DF1JSL
146+
# https://www.github.com/joergschultzelutter/robotframework-aprslib
147+
148+
*** Settings ***
149+
Library AprsLibrary.py
150+
151+
Suite Setup Open APRS-IS Connection
152+
Suite Teardown Close APRS-IS Connection
153+
154+
*** Variables ***
155+
# This is your APRS-IS call sign. Replace this value with your personal call sign
156+
${callsign} YOURCALLSIGN
157+
158+
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
159+
${filter} t/m
160+
161+
*** Test Cases ***
162+
Echo APRS-IS Raw Traffic to Console
163+
[Documentation] Capture up to 10 APRS messages and display them on the console
164+
165+
# Robot has no WHILE loop. Therefore, we need to use a FOR loop.
166+
FOR ${i} IN RANGE 10
167+
Receive Packet From APRS-IS
168+
END
169+
170+
*** Keywords ***
171+
Open APRS-IS Connection
172+
${passcode}= Calculate APRS-IS Passcode ${callsign}
173+
174+
Set APRS-IS Callsign ${callsign}
175+
Set APRS-IS Passcode ${passcode}
176+
Set APRS-IS Filter ${filter}
177+
178+
Log Connecting to APRS-IS
179+
Connect to APRS-IS
180+
181+
Close APRS-IS Connection
182+
Log Disconnect from APRS-IS
183+
Disconnect from APRS-IS
184+
185+
Receive packet from APRS-IS
186+
# Receive the package. By default, aprslib decodes it ...
187+
${packet} = Receive APRS Packet
188+
189+
# ... but for now, let's get the raw message from that decode packet
190+
# and display it on the console
191+
${packet} = Get Raw Message Value From APRS Packet ${packet}
192+
Log To Console ${packet}
193+
```
194+
195+
### Receive a message and send an ack plus response to the user
196+
197+
```robotframework
198+
# This is a VERY simplified test which fails if you send unconfirmed
199+
# messages OR messages with the more modern ack/rej schema to it
200+
#
201+
# Author: Joerg Schultze-Lutter, DF1JSL
202+
# https://www.github.com/joergschultzelutter
203+
204+
*** Settings ***
205+
Library AprsLibrary.py
206+
Library String
207+
208+
Suite Setup Open APRS-IS Connection
209+
Suite Teardown Close APRS-IS Connection
210+
211+
*** Variables ***
212+
213+
# This is your APRS-IS call sign. Replace this value with your personal call sign
214+
${callsign} YOURCALLSIGN
215+
216+
# APRS-IS server filter, see http://www.aprs-is.net/javAPRSFilter.aspx
217+
${filter} g/${callsign}*
218+
219+
*** Test Cases ***
220+
Simple Receive-and-Respond Test Case
221+
[Documentation] Our 'master receiver' task
222+
# The current Robot Framework does not support WHILE loops. This is a still a
223+
# finite loop but as our goal is only to receive a single message, this
224+
# crude approach will do.
225+
Wait Until Keyword Succeeds 50x 0sec Receive Packet From APRS-IS
226+
227+
*** Keywords ***
228+
229+
Receive packet from APRS-IS
230+
[Documentation] VERY simplified ack-and-respond-to-message test case. Sends ack & msg to user, then terminates the test
231+
Log Receive message from APRS-IS
232+
${packet} = Receive APRS Packet
233+
234+
${format_string}= Get Format Value From APRS Packet ${packet}
235+
Run Keyword If '${format_string}' != 'message' Fail msg=Packet format is not 'message'; start new loop
236+
237+
${from_string}= Get From Value From APRS Packet ${packet}
238+
${adresse_string}= Get Adresse Value From APRS Packet ${packet}
239+
${msgtext_string}= Get Message Text Value From APRS Packet ${packet}
240+
241+
# The msgno might not be present for unconfirmed messsages. A failure to extract the msgno
242+
# simply triggers a new WUKS loop. After all, this is a VERY very simplified library demo.
243+
#
244+
# Therefore, I don't care about this case and simply expect to receive a message with a
245+
# msgno present. Additionally, keep in mind that alphanumeric message number qualifiers
246+
# are currently not parsed by the aprslib library. For simpllicity reas
247+
${msgno_string}= Get Message Number Value From APRS Packet ${packet}
248+
249+
# If we have received an ack or a rej, we simply ignore the message and start anew
250+
Run Keyword If '${msgtext_string}' == 'ack' Fail msg=Ignoring ack, start new loop
251+
Run Keyword If '${msgtext_string}' == 'rej' Fail msg=Ignoring rej, start new loop
252+
253+
# show the user what we have received
254+
Log To Console I have received '${msgtext_string}'
255+
256+
# Send the ack
257+
# build the ack based on the incoming message number
258+
${ackmsg} = Format String {}>APRS::{:9}:ack{} ${adresse_string} ${from_string} ${msgno_string}
259+
# and send the ack to APRS-IS
260+
Log To Console Sending acknowledgement '${ackmsg}'
261+
Send Packet to APRS-IS ${ackmsg}
262+
263+
# do not flood the APRS-IS network
264+
Sleep 2sec
265+
266+
# Send the actual message
267+
# Get a message number from the library
268+
${mymsgno}= Get APRS MsgNo As Alphanumeric Value
269+
# Increment the library's message number (not really necessary here as we only deal with one message)
270+
Increment APRS MsgNo
271+
# build the final string
272+
${msg}= Format String {}>APRS::{:9}:{} {}{} ${adresse_string} ${from_string} Hello ${from_string} , your Robot Overlords send greetings!
273+
${msg}= Catenate SEPARATOR= ${msg} { ${mymsgno}
274+
# and send the message to APRS-IS
275+
Log To Console Sending actual message '${msg}'
276+
Send Packet to APRS-IS ${msg}
277+
278+
Log To Console And we're done
279+
280+
Send Packet to APRS-IS
281+
[Documentation] Send packet to APRS-IS
282+
[arguments] ${message}
283+
Log Send Packet to APRS-IS
284+
Send APRS Packet ${message}
285+
286+
Open APRS-IS Connection
287+
[Documentation] Establishes a connection to APRS-IS
288+
${passcode}= Calculate APRS-IS Passcode ${callsign}
289+
290+
Set APRS-IS Callsign ${callsign}
291+
Set APRS-IS Passcode ${passcode}
292+
Set APRS-IS Filter ${filter}
293+
294+
Log Connecting to APRS-IS
295+
Connect to APRS-IS
296+
297+
Close APRS-IS Connection
298+
[Documentation] Closes an existing connection to APRS-IS
299+
Log Disconnect from APRS-IS
300+
Disconnect from APRS-IS
301+
```
182302

183303
## The fine print
184304

0 commit comments

Comments
 (0)