Skip to content

Document non-expiring HiveMQ certificate solution #195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Document non-expiring HiveMQ certificate solution #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
20d54d3
Initial plan
Copilot Oct 22, 2025
20f9bf3
Update docs with non-expiring certificate information
Copilot Oct 22, 2025
d40ee30
Revise certificate instructions for Pico W setup
sgbaird Nov 17, 2025
30a6e08
Revise MQTT warning for HiveMQ Cloud certificates
sgbaird Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/courses/hello-world/1.1-running-the-demo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ the self-driving-lab-demo Python package.
✅ Follow the [video tutorial](https://youtu.be/D54yfxRSY6s) below. Consider printing a hardcopy of the [Build Instructions manuscript](https://doi.org/10.1016/j.xpro.2023.102329) or opening it in a separate tab.

```{warning}
You must copy [the `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) to the Pico W for it to work with recent version of the `self-driving-lab-demo` package. If you swapped out the credentials with your own broker information (required for the assignment), you must [generate your own `hivemq-com-chain.der` file](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb) due to a recent change in HiveMQ's security procedures (as of 2024-07-03).
You must copy [the `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) to the Pico W for it to work with recent version of the `self-driving-lab-demo` package. A non-expiring, "root" certificate is contained in `sdl_demo.zip` packages releases v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The warning starts with "You must copy [the hivemq-com-chain.der file]" (referring to a specific deprecated file) but then immediately recommends using the non-expiring root certificate instead. This creates confusion about which approach users should actually follow.

Suggestion: Restructure to clearly indicate that the old approach (copying the specific file from the repo) is no longer recommended, and the new recommended approach is to use the non-expiring root certificate from releases v0.8.13+. For example:

"For the demo to work with recent versions of the self-driving-lab-demo package, you need a HiveMQ certificate file (hivemq-com-chain.der). A non-expiring, 'root' certificate is now available in sdl_demo.zip packages releases v0.8.13 and beyond [colab]. This is the recommended approach as it works across all HiveMQ instances. Alternatively, you can generate a certificate specific to your HiveMQ instance."

Suggested change
You must copy [the `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) to the Pico W for it to work with recent version of the `self-driving-lab-demo` package. A non-expiring, "root" certificate is contained in `sdl_demo.zip` packages releases v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.
For recent versions of the `self-driving-lab-demo` package, you need a HiveMQ certificate file (`hivemq-com-chain.der`). The recommended approach is to use the non-expiring, "root" certificate included in `sdl_demo.zip` package releases v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)], which works across all HiveMQ instances. Alternatively, for legacy setups or specific HiveMQ instances, you may [generate a certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb) or use the older [`hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der).

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Inconsistent use of "root" in quotation marks. The text uses "root" certificate with quotes, but this should be consistent across the documentation. Since ISRG Root X1 is technically a root certificate, the quotes are unnecessary and may suggest uncertainty about the terminology.

Suggestion: Remove the quotation marks around "root" for consistency and clarity: A non-expiring root certificate is contained in...

Suggested change
You must copy [the `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) to the Pico W for it to work with recent version of the `self-driving-lab-demo` package. A non-expiring, "root" certificate is contained in `sdl_demo.zip` packages releases v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.
You must copy [the `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) to the Pico W for it to work with recent version of the `self-driving-lab-demo` package. A non-expiring, root certificate is contained in `sdl_demo.zip` packages releases v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.

Copilot uses AI. Check for mistakes.
```

<iframe width="560" height="315" src="https://www.youtube.com/embed/D54yfxRSY6s?si=xB5bo7bxWry02q5Q" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
Expand Down
4 changes: 3 additions & 1 deletion docs/courses/hello-world/mqtt-warning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
```{warning}
Recently, HiveMQ Cloud changed such that `hivemq-com-chain.der` (a Certificate Authority (CA) file) is not transferrable across different broker instances. The [latest `hivemq-com-chain.der` file](https://raw.githubusercontent.com/sparks-baird/self-driving-lab-demo/main/src/public_mqtt_sdl_demo/hivemq-com-chain.der) from [`self-driving-lab-demo`](https://github.com/sparks-baird/self-driving-lab-demo) will be hard-coded to the `self-driving-lab-demo` public test credentials (i.e., what is used in Module 1 - Running the Demo), so the *tutorials* should run without issue as long as you are using that file. However, the *assignment* requires you to have your own HiveMQ Cloud broker instance, so you will need to [generate a `hivemq-com-chain.der` file specific to your instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb) and upload it to your microcontroller in place of the default one.
Recently, HiveMQ Cloud changed such that `hivemq-com-chain.der` (a Certificate Authority (CA) file) is not transferrable across different broker instances. However, a **non-expiring certificate solution** is available using the intermediate certificate (ISRG Root X1) instead of the server-specific certificate.
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text refers to "intermediate certificate (ISRG Root X1)" but ISRG Root X1 is actually a root certificate, not an intermediate certificate. This creates confusion about the certificate chain.

Suggestion: Change "using the intermediate certificate (ISRG Root X1)" to "using the root certificate (ISRG Root X1)" for technical accuracy.

Suggested change
Recently, HiveMQ Cloud changed such that `hivemq-com-chain.der` (a Certificate Authority (CA) file) is not transferrable across different broker instances. However, a **non-expiring certificate solution** is available using the intermediate certificate (ISRG Root X1) instead of the server-specific certificate.
Recently, HiveMQ Cloud changed such that `hivemq-com-chain.der` (a Certificate Authority (CA) file) is not transferrable across different broker instances. However, a **non-expiring certificate solution** is available using the root certificate (ISRG Root X1) instead of the server-specific certificate.

Copilot uses AI. Check for mistakes.

A non-expiring, "root" certificate is contained in `sdl_demo.zip` packages [releases](https://github.com/sparks-baird/self-driving-lab-demo/releases) v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Inconsistent use of "root" in quotation marks. In line 4, "root" is quoted ("root" certificate) but the text should either consistently use quotes or not use them at all. Since ISRG Root X1 is technically a root certificate, the quotes are unnecessary and may suggest uncertainty about the terminology.

Suggestion: Remove the quotation marks around "root" for consistency and clarity: A non-expiring root certificate is contained in...

Suggested change
A non-expiring, "root" certificate is contained in `sdl_demo.zip` packages [releases](https://github.com/sparks-baird/self-driving-lab-demo/releases) v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.
A non-expiring, root certificate is contained in `sdl_demo.zip` packages [releases](https://github.com/sparks-baird/self-driving-lab-demo/releases) v0.8.13 and beyond [[colab](https://colab.research.google.com/gist/sgbaird/5ddef425e8d4aae454a69fbce8654faf/hivemq-root-cert.ipynb)]. You can also [generate a `hivemq-com-chain.der` certificate specific to your HiveMQ instance](https://colab.research.google.com/github/sparks-baird/self-driving-lab-demo/blob/main/notebooks/7.2.1-hivemq-openssl-certificate.ipynb). We recommend using the non-expiring, root certificate, which is applicable for all HiveMQ instances.

Copilot uses AI. Check for mistakes.
```
Loading