How boston-dynamics/spot-sdk works
Project type and purpose
• This is not a single‐application codebase but a comprehensive SDK repository (“Spot SDK”) for the Boston Dynamics Spot robot. It includes:
• Protobuf definitions of the Spot API (“protos/…”) and code-generation tooling (“choreography_protos/…”).
• A suite of Python packages (bosdyn-core, bosdyn-client, bosdyn-mission, bosdyn-orbit, bosdyn-scout, bosdyn-choreography-client) under “python/…”, each with its own setup.py.
• Thousands of Python example programs under “python/examples/…”.
• Documentation sources in Markdown under “docs/…” and generated HTML under “docs/html/…”.
• Prebuilt wheel distributions under “prebuilt/…”.
File structure
• Top-level directories:
• “protos”: canonical .proto service definitions ➔ code-gen for server & client stubs.
• “python”: per-package Python modules grouping core utilities, API clients, mission/orbit/scout extensions, choreography.
• “python/examples”: dozens of small demo applications.
• “docs”: conceptual, payload, proto, Python tutorials + Sphinx build output.
• “prebuilt”: precompiled wheel artifacts for easy install.
• “choreography_protos”: specialized protos & packaging for choreography features.
• Build scripts and packaging: setup.py & setup.cfg in each package, requirements files for examples, Sphinx conf for docs.
Architecture overview
1. Spot Robot Onboard Services
– gRPC servers implementing services defined in protos/…
2. Protobuf API Definition Layer
– .proto files under “protos/” & “choreography_protos/”
– protoc code-generation pipeline producing Python stubs
3. Core Python SDK Libraries
– bosdyn-core (geometry, data formats)
– bosdyn-client (auth, channel, generic client classes)
– bosdyn-mission, bosdyn-orbit, bosdyn-scout (domain-specific clients)
– bosdyn-choreography-client (animation & choreographer client)
4. Example Applications & Payload Extensions
– Python scripts & Docker-based plugins demonstrating usage
– Payload ICD docs & payload developer code
5. Documentation Generation
– Markdown sources under docs/
– Sphinx build producing HTML under docs/html/
6. Packaging & Distribution
– setup.py/Cfg per package
– prebuilt wheel files under prebuilt/
c. Architectural patterns & principles:
– Layered architecture:
• API Definition (Protos)
• Transport & Stub Generation (gRPC + codegen)
• Core Library & Clients
• Example & Application Layer
• Documentation Layer
– Separation of Concerns: each Python package focuses on one domain (auth & channels vs. mission vs. orbit).
– Extensibility: examples and payload plugins live in their own directories with Docker/requirements manifest.
d. Key technologies/frameworks:
– gRPC & Protocol Buffers (codegen)
– Python packaging (setuptools, wheels)
– Sphinx (documentation)
– Docker (for payload & example containers)
– Flask or simple Python servers (in some examples)
Details to capture
• multi-package nature of the SDK monorepo.
• Both the code generation and packaging pipelines.
• How prebuilt wheels allow immediate install without local build.
• Versions (e.g., v5.0.1.2).