mikkeli
102cf38082
No dedicated display is in scope, so Class A has nothing to drive and app-hud is cancelled. Records why it will not come back: no connector-powered display exists (DP_PWR is 3.3V/500mA and deliberately unconnected at the sink, HDMI gives 55mA, a panel needs 5-15W), the dev kit exposes no DSI, and a data-only client on one USB cable is simpler anyway. Video out generated the enclosure, power and cabling complexity this project set out to solve. Removing it removed the problem. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
---
|
|
type: reference
|
|
---
|
|
# Repositories
|
|
|
|
## Splitting rule
|
|
|
|
- **`project-yukart`** — overview, roadmap, cross-cutting design. No code, ever.
|
|
- **`orin-nano-env-setup`** — the host: kernel modules, drivers, OS packages,
|
|
device permissions, systemd plumbing. Anything that must be true *before* an
|
|
application starts.
|
|
- **One repo per application or application cluster.** A cluster is a set of
|
|
services that are developed, versioned and deployed together.
|
|
- **Helper/deployment repos** stand alone when they are reusable outside Yukart.
|
|
|
|
Anything cross-repo — topic names, payload schemas, the DBC — belongs in the
|
|
contracts repo, not copied into each consumer.
|
|
|
|
## Current
|
|
|
|
| Repository | Role |
|
|
|---|---|
|
|
| [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture |
|
|
| [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
|
|
| [app-flutter](gitea:yukart/app-flutter) | Flutter display client |
|
|
| [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the HTTP surface |
|
|
| [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance |
|
|
| [tool-mapmint](gitea:yukart/tool-mapmint) | Map artifact minting, workstation-side |
|
|
| [tool-mock](gitea:yukart/tool-mock) | Mocks and fixtures — a fake car on a workstation |
|
|
|
|
## Planned
|
|
|
|
| Repository | Role | Why separate |
|
|
|---|---|---|
|
|
| `contracts` | Topic namespace, payload schemas, Z27AG DBC | Consumed by every other repo, including non-Jetson clients; must not be duplicated |
|
|
| `svc-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin |
|
|
| `app-esp32` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
|
|
| `tool-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |
|
|
|
|
Create these lazily — when there is something to put in them, not before.
|
|
|
|
## Naming
|
|
|
|
Repositories are named `<group>-<thing>`, with **no project prefix**. The `yukart`
|
|
Gitea org already namespaces everything, so a `yukart-` prefix would be a constant
|
|
occupying the most significant characters of every name — pure noise in a sorted
|
|
index, and the reason the earlier scheme scattered.
|
|
|
|
| Group | Meaning |
|
|
|---|---|
|
|
| `svc-` | A service running on the Orin |
|
|
| `app-` | A display client, running off the Orin |
|
|
| `tool-` | Off-car tooling; never deployed to the car |
|
|
|
|
The goal is that **lexical order equals semantic grouping**: opening the org
|
|
listing puts every service together, every client together, every tool together.
|
|
The group segment does that work because it is the first thing that varies.
|
|
|
|
Ungrouped singletons — `contracts` — are fine where a category has exactly one
|
|
member and always will.
|
|
|
|
`project-yukart` and `orin-nano-env-setup` predate this and keep their names
|
|
rather than paying a rename for two repos that are stable and easy to find.
|
|
|
|
### Reusability
|
|
|
|
Nothing in a name marks a repo as reusable. A component that turns out to be
|
|
genuinely reusable outside Yukart **leaves the org** rather than being renamed —
|
|
location says it, not spelling.
|
|
|
|
## Helper and deployment repos
|
|
|
|
Arduino and ESP32 work implies flashing, build and deployment scaffolding that
|
|
is likely to be reused. Keep those generic and outside the org — e.g. an ESP32
|
|
project skeleton with the toolchain, flashing scripts and CI already wired up.
|
|
|
|
### Gitea template repositories
|
|
|
|
Gitea supports these: repo **Settings → Repository → Template**, after which the
|
|
repo offers **"Use this template"** to create new repos from it.
|
|
|
|
Use a template repo for **scaffolding** — a new ESP32 or Arduino project that
|
|
should start with the toolchain, directory layout and flashing scripts in place.
|
|
|
|
Do **not** use one for code you intend to keep updating in one place. Template
|
|
instantiation is a fork-at-create: the copy has no link back, so improvements to
|
|
the template never reach repos already created from it. For genuinely shared
|
|
code, use a git submodule or publish a package instead.
|
|
|
|
Rule of thumb: *template for the starting shape, submodule/package for living
|
|
code.*
|
|
|
|
## Linking convention
|
|
|
|
Cross-repo links use the `gitea:owner/repo` scheme, as established in the hub
|
|
README — e.g. `[Environment setup](gitea:yukart/orin-nano-env-setup)`.
|
|
|
|
## Per-repo document layout
|
|
|
|
Following the convention already set by `orin-nano-env-setup`:
|
|
|
|
```
|
|
README.md minimal portal, points everywhere else
|
|
docs/
|
|
GUIDELINES.md implementation practice for this repo
|
|
BOM.md hardware, where the repo owns hardware
|
|
impl/
|
|
plans/ what is intended
|
|
reports/ what actually happened, and why
|
|
```
|
|
|
|
The `impl/plans` ÷ `impl/reports` split is worth keeping: plans go stale,
|
|
reports do not. A report like `PCAN-SETUP.md` stays valuable precisely because
|
|
it records the investigation and the dead ends, not just the final commands.
|
|
|
|
### Scaffolding conventions
|
|
|
|
No template repository. Template instantiation is fork-at-create, so it could not
|
|
reach repos that already exist, and the scaffolding is a handful of markdown files
|
|
— lighter than the machinery to manage it. A template earns its place where there
|
|
is a real toolchain to carry, which is the ESP32 case above.
|
|
|
|
Every component repo carries:
|
|
|
|
```
|
|
README.md the shared blurb, "What this repo is about", then
|
|
links to guidelines and impl/
|
|
docs/GUIDELINES.md numbered sections, ends "## N. To be added"
|
|
docs/impl/plans/ at least INITIAL.md
|
|
docs/impl/reports/
|
|
docs/BOM.md only where the repo owns hardware
|
|
```
|
|
|
|
### Front matter
|
|
|
|
Every markdown document carries front matter, with **no exceptions for the hub or
|
|
for any particular repo**. The `type` discriminates:
|
|
|
|
| `type` | Applies to | Extra fields |
|
|
|---|---|---|
|
|
| `reference` | READMEs, OVERVIEW, ARCHITECTURE, BOM — things that describe what is | — |
|
|
| `guidelines` | `GUIDELINES.md` | — |
|
|
| `plan` | anything under `impl/plans/`, plus `ROADMAP.md` | `status`, `updated` |
|
|
| `report` | anything under `impl/reports/` | `date` |
|
|
|
|
`status` is one of `active`, `superseded` or `done`.
|
|
|
|
The extra fields exist for one reason. This document already observes that **plans
|
|
go stale and reports do not** — but nothing made staleness visible, so a plan
|
|
written months ago looked identical to one written this morning. `status` and
|
|
`updated` fix that; `date` on a report records the moment it describes, which is
|
|
the whole value of a report.
|
|
|
|
A `type` with one possible value would be decoration. This one has four and they
|
|
are worth grepping for.
|
|
|
|
## Naming
|
|
|
|
Repositories are named `<group>-<thing>`, with **no project prefix**. The `yukart`
|
|
Gitea org already namespaces everything, so a `yukart-` prefix would be a constant
|
|
occupying the most significant characters of every name — pure noise in a sorted
|
|
index, and the reason the earlier scheme scattered.
|
|
|
|
| Group | Meaning |
|
|
|---|---|
|
|
| `svc-` | A service running on the Orin |
|
|
| `app-` | A display client, running off the Orin |
|
|
| `tool-` | Off-car tooling; never deployed to the car |
|
|
|
|
The goal is that **lexical order equals semantic grouping**: opening the org
|
|
listing puts every service together, every client together, every tool together.
|
|
The group segment does that work because it is the first thing that varies.
|
|
|
|
Ungrouped singletons — `contracts` — are fine where a category has exactly one
|
|
member and always will.
|
|
|
|
`project-yukart` and `orin-nano-env-setup` predate this and keep their names
|
|
rather than paying a rename for two repos that are stable and easy to find.
|
|
|
|
### Reusability
|
|
|
|
Nothing in a name marks a repo as reusable. A component that turns out to be
|
|
genuinely reusable outside Yukart **leaves the org** rather than being renamed —
|
|
location says it, not spelling.
|
|
|
|
## Helper and deployment repos
|
|
|
|
Arduino and ESP32 work implies flashing, build and deployment scaffolding that
|
|
is likely to be reused. Keep those generic and outside the org — e.g. an ESP32
|
|
project skeleton with the toolchain, flashing scripts and CI already wired up.
|
|
|
|
### Gitea template repositories
|
|
|
|
Gitea supports these: repo **Settings → Repository → Template**, after which the
|
|
repo offers **"Use this template"** to create new repos from it.
|
|
|
|
Use a template repo for **scaffolding** — a new ESP32 or Arduino project that
|
|
should start with the toolchain, directory layout and flashing scripts in place.
|
|
|
|
Do **not** use one for code you intend to keep updating in one place. Template
|
|
instantiation is a fork-at-create: the copy has no link back, so improvements to
|
|
the template never reach repos already created from it. For genuinely shared
|
|
code, use a git submodule or publish a package instead.
|
|
|
|
Rule of thumb: *template for the starting shape, submodule/package for living
|
|
code.*
|
|
|
|
## Linking convention
|
|
|
|
Cross-repo links use the `gitea:owner/repo` scheme, as established in the hub
|
|
README — e.g. `[Environment setup](gitea:yukart/orin-nano-env-setup)`.
|
|
|
|
## Per-repo document layout
|
|
|
|
Following the convention already set by `orin-nano-env-setup`:
|
|
|
|
```
|
|
README.md minimal portal, points everywhere else
|
|
docs/
|
|
GUIDELINES.md implementation practice for this repo
|
|
BOM.md hardware, where the repo owns hardware
|
|
impl/
|
|
plans/ what is intended
|
|
reports/ what actually happened, and why
|
|
```
|
|
|
|
The `impl/plans` ÷ `impl/reports` split is worth keeping: plans go stale,
|
|
reports do not. A report like `PCAN-SETUP.md` stays valuable precisely because
|
|
it records the investigation and the dead ends, not just the final commands.
|
|
|
|
### Scaffolding conventions
|
|
|
|
No template repository for this. Template instantiation is fork-at-create, so it
|
|
could not reach the repos that already exist, and the scaffolding is three
|
|
markdown files — lighter than the machinery to manage it. A template earns its
|
|
place where there is a real toolchain to carry, which is the ESP32 case above.
|
|
|
|
What every component repo has instead:
|
|
|
|
```
|
|
README.md frontmatter, the shared blurb, "What this repo is
|
|
about", then links to guidelines and impl/
|
|
docs/GUIDELINES.md frontmatter, numbered sections, ends "## N. To be added"
|
|
docs/impl/plans/ at least INITIAL.md
|
|
docs/impl/reports/
|
|
docs/BOM.md only where the repo owns hardware
|
|
```
|
|
|
|
**Frontmatter follows the document's nature, not its location:** living documents
|
|
carry `type: default`; historical records do not. So README, GUIDELINES, BOM and
|
|
plans have it, and reports do not. The hub carries none at all, being the portal
|
|
rather than a component.
|