Skip to content

CLAUDE.md

Latest commit

 

History

History
75 lines (50 loc) · 2.91 KB

CLAUDE.md

File metadata and controls

75 lines (50 loc) · 2.91 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Fleet Protocol is a C API and CMake framework for device-to-cloud communication in internet-unstable environments, developed by BringAuto. The repository defines interfaces only — no implementations. Other projects implement these interfaces.

The protocol has three main actors:

  • Internal Client — runs on a device, communicates with Module Gateway
  • Module Gateway — bridge component with Internal Server, Aggregator, and External Client subsystems
  • External Server — cloud infrastructure

Communication uses Protocol Buffers v3.21.12 with a 4-byte uint32_t message-size header.

Build Commands

Requires CMake ≥ 3.25 and CMlib.

mkdir _build && cd _build

# Build with examples
cmake -DBRINGAUTO_SAMPLES=ON ..
make

# Build for installation/packaging
cmake -DBRINGAUTO_INSTALL=ON -DBRINGAUTO_PACKAGE=ON ..
make install

# Create distributable package
cmake -DBRINGAUTO_INSTALL=ON -DBRINGAUTO_PACKAGE=ON ..
cpack

CMake options: BRINGAUTO_SAMPLES, BRINGAUTO_INSTALL, BRINGAUTO_PACKAGE (enabling PACKAGE forces INSTALL=ON).

Using the Library in Another CMake Project

find_package(fleet-protocol-interface REQUIRED)
target_link_libraries(<target> PUBLIC fleet-protocol-interface::fleet-protocol-interface)

Architecture

All libraries under lib/ are header-only interface libraries — they define C APIs that implementors must fulfil.

Interface Hierarchy

fleet-protocol-interface
├── common-headers-interface          # Shared types: buffer structs, device IDs, error codes
├── internal-client-interface         # init_connection, destroy_connection, send_status, get_command
├── module-gateway-interface          # command_manager, status_aggregator, error_aggregator
└── module-maintainer-*-interface     # What a module must implement for MG and ES

Key Design Decisions

  • All interfaces are C with C++ compatibility guards
  • Memory uses struct buffer { void *data; size_t size_in_bytes; } throughout
  • Thread safety: multiple contexts are safe; a single context is not
  • Communication is status/command based: devices send status, receive commands
  • Error codes: OK = 0, NOT_OK = -1, component-specific negatives (see general_error_codes.h)

Protobuf

Source .proto files are in protobuf/definition/. Pre-compiled bindings for C++, C#, Go, and Python are in protobuf/compiled/. Python bindings are structured as a module under protobuf/compiled/python/.

To recompile protobuf files, see protobuf/README.md for per-language instructions using protoc.

No Tests

There is no test suite in this repository. The examples/protobuf_parsing_example/ directory demonstrates usage patterns for protobuf message serialization/deserialization.