probe-rs/webpage

the probe.rs webpage

The new probe.rs webpage

Goals

• Create a more appealing frontpage that tells the visitor a bit better what we have to offer.
• Provide simple installation instructions. Part of this initiative is building proper release artifacts in the pipeline (see #1721).
• Make the entry into probe-rs usage even easier.
  • Explain how one uses probe-rs run properly.
  • How to troubleshoot
    • How to enable logs
    • What are common errors
      • Can we also add hints in our error messages
  • Clean up docs a lot and explain in more detail.
• Add a searchable list of provided targets with information about each target.

Development

Install deno which is the JS runtime to generate all webpage docs.

Then locally serve the documentation from the root of this repository. Be patient, it may take a while on the first run.

$ deno task serve

When the documentation preview is ready and gets served, you will be greeted with something like:

🍾 Site built into ./target
  129 files generated in 62.64 seconds

  Server started at:
  http://localhost:3000/ (local)
  http://192.0.2.3:3000/ (network)

When doing heavy development, you might end in the need to provide a GitHub API Token (for fetching the probe-rs repository in the background). See here for how to get yours, save it to a file like ~/.probe-rs-github-token and provide it to deno via the environment variable GITHUB_TOKEN as follows:

$ export GITHUB_TOKEN=$(cat ~/.probe-rs-github-token)

webpage's Issues

Use permanent link to latest release

I could not figure out how the current link to the installer script works, but it could just be replaced by a link to

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-installer.sh | sh

Webpage suggests `--list-targets` which is not available

The webpage suggests the following:

# Don't know if your target is available
# and what it's name is?
cargo flash --list-targets

However, cargo flash does not know --list-targets (At least not v.0.8.0) but --list-probes.

Link to target-gen outdated

Describe the bug
In the library's quickstart documentation there is an outdated link pointing to a moved repository.

The "Downloading to flash" section currently reads

Any target that has a CMSIS-Pack can be converted into a probe-rs flash download target with our utility

with "utility" pointing to https://github.com/probe-rs/target-gen.

To Reproduce
Open the quickstart chapter in a browser.

Expected behavior
Above link (i.e. the term "utility") should point to https://github.com/probe-rs/probe-rs/tree/master/target-gen

Recommend J-Link Conifigurator over Zadig to install generic WinUSB driver

The documentation recommends Zadig to install a generic WinUSB driver for J-Link devices on Windows:
https://probe.rs/docs/getting-started/probe-setup/#windows-1

In my opinion, the J-Link Configurator should be the preferred tool since it is published by Segger and supports this functionality (it is also pretty easy to make mistakes with Zadig). In addition, J-Link Configurator is probably the easiest tool to use to restore the J-Link USB driver, should someone need to do so in the future.

This is the home page for the tool itself: https://www.segger.com/products/debug-probes/j-link/tools/j-link-configurator/
And a wiki article showing how to configure a probe to use WinUSB: https://wiki.segger.com/J-Link_on_Windows_ARM

Redirect old links

Since the web has changed a lot, some links that were pointing to it may stop working and could be redirected to the new equivalent page/section, eg: https://probe.rs/docs/tools/vscode/ could be redirected to https://probe.rs/docs/tools/debugger/

Incorrect docs

Describe the bug
On https://probe.rs/docs/knowledge-base/troubleshooting/ it says you should write rttEnabled: true, but it's set outside of the object in the "coreConfigs" array which seems to be incorrect.

"configurations": [{
// SNIP...
"rttEnabled": true,
// SNIP...
"coreConfigs": [{
    // SNIP ...,
    "options": {
        "env": {
            "DEFMT_LOG": "Trace" // Trace, Debug, Info, Warn, Error
            }
        },
    }
],
"consoleLogLevel": "Console", //Console, Info, Debug

To Reproduce
Follow the documentation.

Additional context
The JSON in the docs doesn't have balanced open/close brackets. The lack of indentation doesn't help with making it clear what properties go inside what objects. The uppercase first letter in "Trace" is non-conventional for Rust (and as far as I can tell, not necessary?). I'm not sure if rttEnabled is actually supposed to be outside of coreConfigs, from looking at this it seems not?

Suggested fix
Something like this might be nicer

{
    "version": "0.2.0",
    "configurations": [{
        // SNIP...
        "coreConfigs": [{
            // SNIP ...,
            "options": {
                "env": {
                    "DEFMT_LOG": "trace" // trace, debug, info, warn, error
                }
            },
            "rttEnabled": true
        }],
        "consoleLogLevel": "Console" //Console, Info, Debug
    }]
}

Correct `probe.rs/docs/getting-started/installation` package dependencies

The probe.rs website reports different dependent packages for Ubuntu compared to the README.md:

# probe.rs
sudo apt install -y pkg-config libusb-1.0-0-dev libftdi1-dev
# README.md
sudo apt install -y libusb-1.0-0-dev libftdi1-dev libudev-dev libssl-dev

• libssl-dev is a required dependency which provides access to openssl
• lib-udev is required by the libudev-sys crate

This was particularly painful for me because compiling code on my Raspberry Pi takes ~10 minutes, and I ended up recompiling code 3-4 installing missing dependencies.

I couldn't find the source code for probe.rs, but I'd be happy writing a PR for it if you could point me to the file.