docs(simulation): add Hawkeye visualizer, replace jMAVSim in SIH docs#26965
docs(simulation): add Hawkeye visualizer, replace jMAVSim in SIH docs#26965
Conversation
|
No broken links found in changed files. |
… docs Hawkeye is a real-time 3D flight visualizer (not a simulator) that replaces jMAVSim's display-only mode for SIH. Adds a dedicated Hawkeye docs page covering installation, SIH SITL usage, multi-vehicle support, and ULog replay. Updates the SIH page to recommend Hawkeye instead of jMAVSim for visualization. Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
hamishwillee
force-pushed
the
mrpollo/docs-hawkeye-visualizer
branch
from
1550c1f to
e63026c
Compare
💡 Commit messages could be improvedNot blocking, but these commit messages could use some cleanup.
See the commit message convention for details. This comment will be automatically removed once the issues are resolved. |
| Download the `.deb` package from the [latest release](https://github.com/PX4/Hawkeye/releases/latest): | ||
|
|
||
| ```sh | ||
| sudo dpkg -i hawkeye_*_amd64.deb | ||
| ``` |
There was a problem hiding this comment.
I did this in WSL2 on Ubuntu 22.04
curl -L -O https://github.com/PX4/Hawkeye/releases/download/v0.2.0/hawkeye_0.2.0_amd64.deb
sudo dpkg -i hawkeye_0.2.0_amd64.deb
Got this error
$ hawkeye
hawkeye: /lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.38' not found (required by hawkeye)
There was a problem hiding this comment.
This will only work for Ubuntu, not WSL. We don't have an installer for Windows right now
There was a problem hiding this comment.
@mrpollo No - WSL2 is Ubuntu :-). Claude tells me this is a problem with running on Ubuntu 22.02.:
Hawkeye requires glibc 2.38+, which ships with Ubuntu 23.10+. WSL2 often runs Ubuntu 22.04 LTS, which only has glibc 2.35.
Sure enough, Hawkeye launces on Ubuntu 24 in WSL2. I will continue testing, but we should note the limitation since PX4 states support for Ubuntu 22 still. We should also look at a deployment mechanism that won't break this.
Can you add the note you want to see?
I can, but it depends on whether this gets "fixed" or just lived with.
I mean we might say "this works on Ubuntu 24 but if you need other versions you can build from source", or we might supply a Ubuntu 22 version.
| In one terminal, start SIH: | ||
|
|
||
| ```sh | ||
| make px4_sitl_sih sihsim_quadx |
There was a problem hiding this comment.
I think this is all good. Can we add instructions for using it with the SIH binaries?
There was a problem hiding this comment.
Perhaps this should go in after that update?
| By default, Hawkeye renders a quadrotor. | ||
| Use flags to select a different model: | ||
|
|
||
| | Flag | Vehicle | | ||
| | ----- | --------------------- | | ||
| | `-mc` | Multicopter (default) | | ||
| | `-fw` | Fixed-wing | | ||
| | `-ts` | Tailsitter | | ||
|
|
||
| Example for fixed-wing: | ||
|
|
||
| ```sh | ||
| hawkeye -fw | ||
| ``` |
There was a problem hiding this comment.
Once you are connected to a vehicle Hawkeye select the correct vehicle type - i..e you can set FW but if you are simulating a copter then Hawkeye will change the rendering to a copter.
In other words this doesn't really do anything, at least for the types I tried.
Add a note?
There was a problem hiding this comment.
@mrpollo A couple of changes needed. This is pretty excellent though. Main question is whether this should go in after the simulation deb file changes or before - either way it (will) needs instructions on working with the new containers.
…iagrams Expand the Hawkeye visualizer docs from a single index.md to a full multi-page guide covering all features: - index.md: hero, installation, getting started (3 progressive paths) - cli.md: command-line reference with all flags and examples - views.md: camera modes, ortho views, themes, vehicle models - hud.md: Console + Tactical HUD modes, debug overlay, annunciators - world_indicators.md: trails (directional/speed ribbon/drone color), ground track, correlation line and curtain overlays - replay.md: ULog replay, transport controls, markers - multi_drone.md: deconfliction, takeoff alignment, correlation analysis - sitl.md: single vehicle + multi-instance swarm + MAVSDK test script - reference.md: keyboard shortcuts, position data tiers, coordinate systems - troubleshooting.md: common problems and fixes by symptom Includes 36 assets: annotated HUD diagrams (SVG), screenshots (PNG), interaction GIFs, marker types diagram, position tier flowchart, and coordinate system reference. YouTube embed for SITL quickstart video.
Reduced total asset size from ~110 MB to 10 MB. Every file now under 1 MB. Large GIFs cropped and scaled down, converted to animated WebP where needed.
|
/en/sim_hawkeye/troubleshooting.md
|
|
Closing in favor of a slimmer PR. After discussing with @hamishwillee, we decided the deep Hawkeye documentation (HUD, replay, multi-drone, CLI reference, etc.) should live in the Hawkeye repo instead of the PX4 user guide. It's now hosted at https://px4.github.io/Hawkeye/. I'll open a new, smaller PR that keeps the SIH page updates (jMAVSim → Hawkeye references, port 19410 label) and adds a short |
|
This was the right thing to do @mrpollo - the docs on https://px4.github.io/Hawkeye/ can now exist without the compromises we have in PX4 repo. ... and they look great. |
3 participants
Adds a dedicated docs page for Hawkeye, a real-time 3D flight visualizer for PX4. Hawkeye is a visualizer, not a simulator -- it renders vehicle state from MAVLink
HIL_STATE_QUATERNIONmessages with zero runtime dependencies.The SIH simulation page previously recommended jMAVSim in display-only mode for visualization. This replaces those references with Hawkeye, which is purpose-built for this role and supports multi-vehicle swarm visualization, ULog replay with ghost mode, and multiple vehicle models.
Changes:
docs/en/sim_hawkeye/index.mdcovering installation (Homebrew, deb, source), SIH SITL usage, multi-vehicle support, ULog replay, CLI reference, and camera controlsdocs/en/sim_sih/index.mdto recommend Hawkeye instead of jMAVSim for 3D visualizationSUMMARY.mdnavigation