Skip to content

Commit 0f43776

Browse files
PeterJCLawPeterJCLaw
committed
First pass at documenting the (simulated) robot radio
This covers the radar-like sweep function, but nothing else as yet.
1 parent 7c8dcbf commit 0f43776

File tree

3 files changed

+168
-0
lines changed

3 files changed

+168
-0
lines changed

‎_data/sidebar_tree.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ tree:
7171
title: Motors
7272
- url: /programming/sr/power/
7373
title: Power
74+
- url: /programming/sr/radio/
75+
title: Radio
7476
- url: /programming/sr/ruggeduinos/
7577
title: Ruggeduinos
7678
tree:

‎programming/sr/radio/index.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
layout: page
3+
title: Radio
4+
---
5+
6+
Radio
7+
=====
8+
9+
<div class="info">
10+
This documentation refers to a feature which is only available within the simulator.
11+
</div>
12+
13+
The `sr.robot` library contains support for detecting radio transmitters with the simulated radio unit on the robot.
14+
Radio transmitters are attached to various items in the Student Robotics arena.
15+
Each transmitter encodes their identity in a machine-readable way, which means that robots can identify these objects.
16+
17+
Using the signal strength of received radio signals, the robot api is able to
18+
determine the distance and direction of a transmitter in 3D space relative to
19+
the radio. Therefore, if the robot can detect transmitters that is at a fixed
20+
location in the arena, a robot can calculate its exact position in the arena.
21+
22+
The `sr.robot` library provides this through a `radio` attached to your `Robot`,
23+
which is can perform a `sweep` to detect transmitters:
24+
25+
~~~~~ python
26+
from sr.robot import *
27+
R = Robot()
28+
transmitters = R.radio.sweep()
29+
~~~~~
30+
31+
When called, the `sweep` function uses the radio reciever as a secondary radio, searching for nearby transmitters.
32+
It returns a list of `Transmitter` objects, each of which describes one of the transmitters that were found within range.
33+
A detailed description of the attributes of Transmitter objects is provided [later in this page](#Transmitter).
34+
35+
Here's an example that will repeatedly print out the distance to each arena transmitter that the robot can see:
36+
37+
~~~~~ python
38+
from sr.robot import *
39+
R = Robot()
40+
41+
while True:
42+
transmitters = R.radio.sweep()
43+
print("I found", len(transmitters), "transmitters:")
44+
45+
for tx in transmitters:
46+
if tx.info.transmitter_type == TransmitterType.BEACON:
47+
print(" - Transmitter #{0} is {1} metres away".format(
48+
tx.info.code,
49+
tx.dist,
50+
))
51+
~~~~~
52+
53+
[Definition of Axes](#axes) {#axes}
54+
===================================
55+
56+
<!-- Note: these are the same as the camera. We should keep these in sync. -->
57+
58+
The radio system describes the transmitters it can see using three coordinate
59+
systems. These are intended to be complementary to each other and contain the
60+
same information in different forms.
61+
62+
The individual coordinate systems used are detailed below on the
63+
[`Point`](#Point) object, which represents a point in space.
64+
65+
The axis definitions match those in common use, as follows:
66+
67+
x-axis
68+
: The horizontal axis running left-to-right in front of the robot.
69+
Rotation about this axis is equivalent to leaning towards or away from
70+
the robot.
71+
72+
y-axis
73+
: The vertical axis running top-to-bottom in front of the robot.
74+
Rotation about this axis is equivalent to turning on the spot,
75+
to the left or right.
76+
77+
z-axis
78+
: The axis leading away from the front of the robot to infinity.
79+
Rotation about this axis is equivalent to being rolled sideways.
80+
81+
[Objects of the Radio System](#radio_objects) {#radio_objects}
82+
==============================
83+
84+
[`Transmitter`](#Transmitter) {#Transmitter}
85+
----------
86+
A `Transmitter` object contains information about a *detected* transmitter.
87+
It has the following attributes:
88+
89+
info
90+
: A [`TransmitterInfo`](#TransmitterInfo) object containing information about the type of transmitter that was detected.
91+
92+
position
93+
: A [`Point`](#Point) describing the position of the transmitter.
94+
95+
dist
96+
: An alias for `position.polar.length`
97+
98+
rot_y
99+
: An alias for `position.polar.rot_y`
100+
101+
timestamp
102+
: The timestamp at which the sweep happened (a float).
103+
104+
[`TransmitterInfo`](#TransmitterInfo) {#TransmitterInfo}
105+
--------------
106+
107+
The `TransmitterInfo` object contains information about a transmitter.
108+
It has the following attributes:
109+
110+
code
111+
: The numeric code of the transmitter.
112+
113+
transmitter_type
114+
: The type of object that this transmitter represents.<br />
115+
The possible values of this are part of the `TransmitterType` enum:
116+
117+
* `TransmitterType.BEACON`
118+
* `TransmitterType.TOWER`
119+
* `TransmitterType.ROBOT`
120+
121+
offset
122+
: The offset of the numeric code of the transmitter from the lowest numbered transmitter of its type.
123+
For example: transmitters 2 and 3, which are the lowest numbered transmitters that represent towers, have offsets of 0 and 1 respectively.
124+
125+
[`Point`](#Point) {#Point}
126+
---------
127+
128+
<!-- Note: this is almost identical to the equivalent type in the vision system. We should keep these in sync. -->
129+
130+
A `Point` object describes a position in three different ways.
131+
These are accessed through the following attributes:
132+
133+
<!-- Deliberately no `image` member -->
134+
135+
world
136+
: The [Cartesian coordinates](https://en.wikipedia.org/wiki/Cartesian_coordinate_system) of the point in 3D space.
137+
This has three attributes: `x`, `y`, and `z`, each of which specifies a distance in metres.
138+
Positions in front of, to the right, or above the robot are positive.
139+
Positions to the left or below are negative.
140+
141+
polar
142+
: The [polar coordinates](https://en.wikipedia.org/wiki/Polar_coordinate_system) of the point in 3D space.<br />
143+
This has three attributes:
144+
145+
length
146+
: The distance to the point.
147+
148+
rot_x
149+
: Rotation about the x-axis in degrees.
150+
Positions above the radio are positive.
151+
152+
rot_y
153+
: Rotation about the y-axis in degrees.
154+
Positions to the right of the radio are positive.
155+
156+
For example, the following code displays the polar coordinate of a `Point` object `p`:
157+
158+
~~~~~ python
159+
print("length", p.polar.length)
160+
print("rot_x", p.polar.rot_x)
161+
print("rot_y", p.polar.rot_y)
162+
~~~~~

‎programming/sr/vision/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ The Logitech C500 has a [field of view][fov] of 72&deg; and the C270 has a field
9393
[Definition of Axes](#axes) {#axes}
9494
===================================
9595

96+
<!-- Note: these are the same as the radio. We should keep these in sync. -->
97+
9698
The vision system describes the markers it can see using three coordinate
9799
systems. These are intended to be complementary to each other and contain
98100
the same information in different forms.
@@ -186,6 +188,8 @@ size
186188
[`Point`](#Point) {#Point}
187189
---------
188190

191+
<!-- Note: this is almost identical to the equivalent type in the radio system. We should keep these in sync. -->
192+
189193
A `Point` object describes a position in three different ways.
190194
These are accessed through the following attributes:
191195

0 commit comments

Comments
 (0)