Skip to main content
← Back to Blog

Part 6: The RCAN Spec Repository and Website

• 2 min read • By Craig Merry
Robotics RCAN Open Source Astro Series

Welcome to Part 6 of our series on building the Robot Communication & Addressing Network (RCAN). In previous posts, we explored the theoretical underpinnings of RCAN, the RURI specification, and the role-based access control model. Today, we’re shifting gears to look at the meta-layer: the repository and website that house the specification itself.

The Repo

The RCAN Spec repository is the source of truth for the protocol. We chose to open-source the specification from day one to foster community collaboration. The repository is more than just a collection of markdown files; it’s a living software project that includes:

  1. The Specification Text: Written in Markdown and MDX.
  2. The Website: A performant static site built with Astro.
  3. Conformance Tests: Automated tests to verify implementations.
  4. Registry Data: JSON schemas and data for the global robot registry.

Why Astro?

We chose Astro for the RCAN website because of its performance and flexibility. The spec needs to be accessible, fast, and easy to read on any device. Astro’s “Zero JS, by default” architecture ensures that the site loads instantly, while its support for MDX allows us to embed interactive components directly into the specification documents.

Project Structure

If you’re looking to contribute, here’s a quick tour of the src directory in the rcan-spec repo:

  • src/content: Contains the structured data collections, such as the robots registry.
  • src/pages: The file-based routing for the website. You’ll find the core documentation pages under src/pages/docs.
  • src/components: Reusable UI components like the FeatureGrid, CodeWindow, and SiteHeader.
  • src/layouts: Layout templates that ensure consistency across the site. DocsLayout is particularly important for the documentation section.

Contributing

We welcome contributions! Whether it’s fixing a typo in the spec, adding a new conformance test, or improving the website’s design, your help is valuable.

  1. Fork the repo on GitHub.
  2. Create a branch for your feature or fix.
  3. Make your changes. If you’re editing the spec, look for the relevant .astro or .md files in src/pages/docs.
  4. Run tests (if applicable) and preview the site locally with npm run dev.
  5. Submit a Pull Request.

What’s Next?

We are working on standardizing the Discovery Protocol (Part 7, coming soon), which will define how robots announce their presence on a local network using mDNS. Stay tuned!