Skip to content
gunkslab

Guides

Set up the overhead camera

A network camera over the desk, looking down, tells the station where each real bot is: the position service reads the markers on the desk’s corners and on each bot, and publishes each bot’s pose, as the simulator does for its own. With it, real bots show on the page’s desk map, a click on the desk sends one there, and the acceptance run can judge the car without a tape measure.

It hasn’t run against a real camera yet. On desks the tests draw it reads a bot to under a millimetre; a real camera’s numbers are to be measured (see the end).

What you need

  • A network camera that serves its picture as a stream, by an address: RTSP (rtsp://..., what most Wi-Fi cameras offer) or HTTP MJPEG (http://..., what phone camera apps offer). 1080p or more. The service reads it over the network, so it doesn’t matter which machine the camera is near. This desk’s is a Tapo C121 (below).
    • Give it a fixed address on the network (a reservation in the router), so its address doesn’t change.
    • Turn off its night vision (the infrared lights), any picture flip or rotation, and any digital zoom.
  • Somewhere to fix it, about 1.1 m above the desk, looking down, with the whole desk in its picture. Straight down is best; from a shelf at an angle works too. Once it’s calibrated, it mustn’t move or zoom.
  • A printer, and something flat and stiff to glue the checkerboard to (card or foam board).

The Tapo C121

The C120 in black: 2560 × 1440, 2.4 GHz Wi-Fi only, and RTSP once it has a camera account. In the Tapo app, before anything else:

  • Update its firmware. C120s on firmware 1.3.1 were reported dropping the full-size stream; the next version fixed it.
  • Camera account: the camera’s settings, Advanced Settings, Camera Account. A username and a password, 6 to 32 characters each, not the Tapo account’s password. They go in its address (step 4), and in Vault.
  • Video quality: Best Quality. The full-size stream follows it.
  • Night vision and the spotlights off.
  • Cloud recording (Tapo Care), the memory card and RTSP: two at most. With all three on, the camera drops RTSP.
  • The date it prints on the picture: if it lands on a field marker, turn it off or move the camera.

Its view is 103° across and 55° top to bottom. At 1.1 m up it sees about 2.8 × 1.15 m, so a 1.2 × 0.8 m desk fits with its long side across the picture. At about 0.8 m the desk’s depth fills the picture top to bottom, so keep it higher. Higher up, each bot’s marker covers fewer pixels: about 59 across at 0.9 m, 47 at 1.1 m and 39 at 1.3 m.

1. Print the markers and the checkerboard

scripts/position print

That writes position/local/markers.png and position/local/checkerboard.png (position/local/ is kept out of git). Print both at 100%, actual size, not “fit to page”. Measure the 100 mm bar on each page: a page printed at another scale makes a bot’s marker read as the wrong height.

2. Lay out the field

The four field markers set the field: where x and y are measured from, as on the simulator’s desk.

  • Marker 0 at the desk’s corner that’s the origin, 1 at the far end of its width (x), 2 in the opposite corner, 3 at the far end of its depth (y): anticlockwise, seen from above.
  • Each one’s centre 30 mm in from both edges of its corner (--inset says otherwise).
  • Flat and taped down. Which way each one is turned doesn’t matter.

If they’re the wrong way round (1 and 3 swapped), or the desk size given doesn’t match where they are, it says so.

3. Mark the bots

One marker each, from 10 up, with its top towards the bot’s front.

  • gl_zero: its marker isn’t placed yet. Until it is, the service takes the earlier desk bot’s lid: a 48 mm field, centred, 65 mm up. Give a different height with --bot, below.
  • Pirate Stage: its marker isn’t designed yet. Until it is, give its height above the desk (and its size, to check the height by) with --bot, below.

A marker stuck on off the middle, or turned, is fine: say so with ahead=, left= and turn= (scripts/position options).

4. The camera’s address

The service reads it from CAMERA_URL, so a password in it never shows in a command line:

export CAMERA_URL='rtsp://USER:PASSWORD@192.168.1.60:554/stream1'     # the Tapo: its camera account, full size
export CAMERA_URL='http://192.168.1.61:8080/video'                     # a phone camera app

On the Tapo, stream1 is the full-size picture and stream2 a smaller one. Use stream1: the lens’s calibration is for one picture size, and the service refuses frames of another.

The password is a secret: keep it in Vault with the broker’s logins, not in a file in the repo.

5. Calibrate the lens

Once per camera, and again if its resolution or zoom changes. Glue the checkerboard flat, then:

scripts/position calibrate

Hold the board up in the camera’s view, all of it in the picture, and keep it still for a moment at each place: near each corner of the picture and in the middle, nearer and further, tipped each way. It says each time it keeps a view, and after 15 it writes position/local/lens.json. It refuses a fit more than 1 pixel off: a board that isn’t flat, or views blurred by moving.

6. Start it

scripts/broker up
scripts/position up --bot 10=bot-a4cf12 --bot 11=bot-b31d07 --desk 1.2x0.8
scripts/position logs

--bot once for each bot: its marker, then its ID. --desk is the field’s size, between the desk’s corners. The log says what it can see:

It says Means
field: all four markers seen, the camera 1.10 m above the desk It’s placed the camera. Check the height against a tape
field: can't see field marker 2, going by the last view that had all four Something’s on marker 2 (a bot parked on it): it carries on
sim-1: in sight, sim-1: out of sight A bot’s marker found, or not seen for a second
bot-a4cf12: its marker measures 51.2 mm, not 48.0 Its height is wrong, or its marker printed at another scale
9.7 frames a second, 16 ms from a frame arriving to its poses sent Every 30 s: whether it’s keeping up
can't open ..., no frames for 2 s The camera’s off or unreachable; the line before says why. It keeps trying

Real bots now show on the page’s desk map, and go-tos work.

How good is it

To be measured on the real camera, for F6.3: put a bot on a taped point, measure where its middle is with a tape, and compare with its pose (scripts/broker sub -t 'gunkslab/v0/desk/+/pose' -v), in the middle of the desk and at each corner. The 16 ms it logs starts when a frame arrives: the camera’s own delay before that isn’t in it, and is to be measured too.

On a broker that takes logins it logs in as position: Run the programs with a login.