Eve library

Galatea Domain - Developer Guide

Guide

Revision 1

On this page

Comprehensive development guide for the Galatea robotics, kinematics, and fashion robotics domain.


Prerequisites#

Required Software#

Tool Version Purpose
Node.js >= 20.0 Runtime for all Galatea libraries
pnpm >= 10.0 Package manager (workspace protocol)
Git >= 2.40 Version control
TypeScript ^6.0.3 Compile-time type checking (via catalog)

Mathematical and Physics Background#

Developers working on the motion and kinematics layers should be familiar with:

  • Linear algebra - Matrix operations, homogeneous transformations, quaternion rotations, Jacobian matrices
  • Rigid body dynamics - Newton-Euler formulation, inertia tensors, torque computation
  • Denavit-Hartenberg parameters - Standard and modified DH conventions for kinematic chain representation
  • Control theory - PID control, impedance/admittance control, task-space and null-space optimization
  • Coordinate frames - World, base, joint, and end-effector reference frames

Robotics-Specific Tooling (Optional)#

These tools are not required for library development but are useful for simulation and integration testing:

Tool Purpose
ROS 2 Integration testing via @galatea/communication DDS bridge
Gazebo / MuJoCo Physics simulation for testing kinematics and dynamics
URDF editors Creating/editing robot description files
EtherCAT tools Debugging real-time motor control communication

Environment Variables#

No environment variables are required for building or unit-testing Galatea libraries. All configuration is handled through the Zod-validated configuration schemas in @galatea/core.


Project Structure#

The Galatea domain contains 20 libraries under libs/galatea/:

text
libs/galatea/
  ai/                      # VLA runtime, behavioral engine, RL, teleoperation
  analytics/               # Engagement tracking, A/B testing, revenue attribution
  choreography/            # Show designer, DSL, formations, music sync, lighting
  communication/           # EtherCAT, CAN FD, DDS bridge, WiFi mesh, PTP sync
  core/                    # Foundation: types, constants, utils, errors, config
  database/                # Persistence: pose-store, event-store, telemetry-store
  event-handlers/          # Robot, safety, garment, show, customer event handlers
  firmware/                # Motor drivers, sensor interfaces, RTOS, bootloader
  fleet/                   # Orchestrator, OTA updates, RaaS billing, diagnostics
  garment-management/      # Outfit tracking, cloth manipulation, quick-change
  hardware-abstraction/    # Joint interface, sensors, face/hand, thermal, RFID
  inclusivity/             # Accessibility, body profiles, cultural config, i18n
  kinematics/              # Forward/inverse kinematics, dynamics, collision, URDF
  locomotion/              # Gait planning, balance, footstep planning, stairs
  perception/              # Audience awareness, SLAM, depth, person detection
  pose-engine/             # Breathing simulation, contrapposto, pose library
  safety/                  # ISO 13482 compliance, force limiting, emergency systems
  sdk/                     # TypeScript client SDK for external developers
  simulation/              # Physics engine, cloth sim, digital twin, RL env
  whole-body-control/      # Task-space, impedance, admittance, postural control

Individual Library Layout#

text
libs/galatea/<library>/
  package.json             # Name, version, ESM exports, zod dependency
  project.json             # Nx config with dependsOn: ["^build"]
  tsconfig.json            # Extends tsconfig.base.json
  tsconfig.lib.json        # Library compilation config
  tsconfig.spec.json       # Test compilation config
  vitest.config.ts         # Vitest config with project root
  src/
    index.ts               # Barrel export + GALATEA_LIBRARY_ID constant
    <module>/
      index.ts             # Module barrel
      <file>.ts            # Implementation
      <file>.spec.ts       # Co-located tests

Local Development Setup#

Initial Setup#

bash
# Clone the repository
git clone git@github.com:GreyChimp/oshun.git
cd oshun

# Install all dependencies
pnpm install

No Infrastructure Required#

Galatea libraries are library-only and do not require running services. The @galatea/database library defines persistence schemas but does not require a running database for unit testing (schemas are validated structurally).


Building Libraries#

Build a Single Library#

bash
pnpm nx build @galatea/core

Build All Galatea Libraries#

bash
pnpm nx run-many --target=build --projects=tag:scope:galatea

Build Order#

Galatea libraries use "dependsOn": ["^build"] in their build targets, ensuring that dependencies are built first. The build order follows:

  1. @galatea/core (no dependencies)
  2. @galatea/hardware-abstraction, @galatea/safety (depend on core)
  3. @galatea/kinematics (depends on core, hardware-abstraction)
  4. @galatea/whole-body-control, @galatea/locomotion (depend on kinematics)
  5. Higher-level libraries (fleet, choreography, ai, etc.)

Build Configuration#

json
{
  "build": {
    "executor": "@nx/js:tsc",
    "dependsOn": ["^build"],
    "outputs": ["{options.outputPath}"],
    "options": {
      "outputPath": "dist/libs/galatea/core",
      "main": "libs/galatea/core/src/index.ts",
      "tsConfig": "libs/galatea/core/tsconfig.lib.json",
      "assets": []
    }
  }
}

Build output goes to dist/libs/galatea/<library>/.


Testing#

Run Tests for a Single Library#

bash
pnpm nx test @galatea/core

Run All Domain Tests#

bash
pnpm nx run-many --target=test --projects=tag:scope:galatea

Watch Mode#

bash
npx vitest --config libs/galatea/kinematics/vitest.config.ts --watch

Test Configuration#

Galatea libraries use a vitest configuration that sets the root to the project directory:

typescript
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';

const projectRoot = dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  root: projectRoot,
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.{test,spec}.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html', 'lcov'],
      include: ['src/**/*.ts'],
      exclude: ['src/**/*.{test,spec}.ts', 'src/**/index.ts'],
    },
  },
});

Key differences from other domains:

  • Uses import.meta.url to resolve the project root directory
  • Coverage includes lcov reporter (useful for CI coverage reporting)
  • Coverage excludes barrel index.ts files

Coverage#

bash
npx vitest --config libs/galatea/kinematics/vitest.config.ts --coverage

Coverage output lands in coverage/libs/galatea/<library>/.

Testing Patterns for Kinematics#

Forward kinematics tests should verify end-effector positions against known DH parameter chains. Use toBeCloseTo for floating-point comparisons:

typescript
describe('forwardKinematics', () => {
  it('computes end-effector position for a 2-link arm', () => {
    const result = computeFK(jointAngles, dhParams);
    expect(result.position.x).toBeCloseTo(expectedX, 6);
    expect(result.position.y).toBeCloseTo(expectedY, 6);
  });
});

Inverse kinematics tests should verify that the IK solution, when fed back through FK, returns the original target position within tolerance.

Collision detection tests should verify that known intersecting geometries report collisions and non-intersecting geometries do not.

Testing Patterns for Safety#

ISO 13482 compliance tests should verify that force limits are enforced and emergency stop transitions occur within specified time bounds.

Force limiting tests should verify that commanded torques are clipped to safe maximums and that the system transitions to a safe state when limits are exceeded.


Linting#

Lint a Single Library#

bash
pnpm nx lint @galatea/kinematics

Lint All Galatea Libraries#

bash
pnpm nx run-many --target=lint --projects=tag:scope:galatea

Common Development Tasks#

Adding a New Library#

  1. Create the directory:
bash
mkdir -p libs/galatea/new-library/src
  1. Create project.json with dependsOn: ["^build"]:
json
{
  "name": "@galatea/new-library",
  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/galatea/new-library/src",
  "projectType": "library",
  "tags": ["scope:galatea", "type:lib", "layer:domain"],
  "implicitDependencies": ["@galatea/core"],
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"],
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/galatea/new-library",
        "main": "libs/galatea/new-library/src/index.ts",
        "tsConfig": "libs/galatea/new-library/tsconfig.lib.json",
        "assets": []
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/galatea/new-library/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/libs/galatea/new-library"],
      "options": {
        "config": "libs/galatea/new-library/vitest.config.ts"
      }
    }
  }
}
  1. Create package.json:
json
{
  "name": "@galatea/new-library",
  "version": "0.1.0",
  "description": "Galatea new-library module",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts"
    }
  },
  "files": ["dist", "src"],
  "dependencies": {
    "zod": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:"
  }
}
  1. Create src/index.ts with the library identifier:
typescript
export * from './implementation/index.js';

export const GALATEA_LIBRARY_ID = '@galatea/new-library';
export const getGalateaLibraryId = (): string => GALATEA_LIBRARY_ID;
  1. Add path mapping to tsconfig.base.json (Galatea uses per-library mappings rather than a wildcard pattern):
json
{
  "@galatea/new-library": ["libs/galatea/new-library/src/index.ts"]
}
  1. Run pnpm install.

Working with Zod Schemas#

All Galatea libraries use Zod for runtime schema validation. This is a domain convention enforced across all 20 libraries:

typescript
import { z } from 'zod';

export const JointAngleSchema = z.object({
  joint: z.string(),
  angle: z.number().min(-Math.PI).max(Math.PI),
  velocity: z.number().optional(),
  torque: z.number().optional(),
});

export type JointAngle = z.infer<typeof JointAngleSchema>;

Adding Sub-Module Path Exports#

Some Galatea libraries expose deep imports (e.g., @galatea/database/pose-store, @galatea/inclusivity/body-profiles). These require explicit path mappings in tsconfig.base.json:

json
{
  "@galatea/database/pose-store": [
    "libs/galatea/database/pose-store/src/index.ts"
  ]
}

Key Patterns and Conventions#

Library Identifier Pattern#

Every Galatea library exports a GALATEA_LIBRARY_ID constant and a getGalateaLibraryId() function:

typescript
export const GALATEA_LIBRARY_ID = '@galatea/kinematics';
export const getGalateaLibraryId = (): string => GALATEA_LIBRARY_ID;

This enables runtime module identification and is required for all libraries in the domain.

Dependency Layering#

The domain follows a strict five-layer architecture:

  1. Core (@galatea/core) - Types, constants, utilities, errors
  2. Hardware (hardware-abstraction, firmware, safety, communication)
  3. Motion (kinematics, whole-body-control, locomotion, pose-engine)
  4. Intelligence (perception, ai, simulation)
  5. Application (fleet, choreography, garment-management, analytics, sdk)

Libraries may only depend on libraries at the same or lower layer. Never introduce upward dependencies.

Implicit Dependencies#

Galatea libraries declare implicitDependencies in their project.json to inform Nx of the build order:

json
{
  "implicitDependencies": ["@galatea/core", "@galatea/hardware-abstraction"]
}

Zod Validation Everywhere#

All public API inputs and configuration objects must be validated through Zod schemas. This provides runtime type safety for data coming from external systems (sensor readings, network messages, user configuration).

ESM Module System#

All libraries use ESM ("type": "module"). Import paths use .js extensions:

typescript
export * from './forward-kinematics/index.js';
export * from './inverse-kinematics/index.js';

Project Tags#

json
["scope:galatea", "type:lib", "layer:domain"]

Individual libraries may add additional tags like "galatea:core" or "galatea:kinematics" for finer-grained filtering.


Debugging Tips#

Floating-Point Precision in Kinematics#

Kinematics computations involve many matrix multiplications that accumulate floating-point errors. When tests fail:

  • Use toBeCloseTo(expected, numDigits) where the precision threshold is 5 * 10^(-numDigits - 1)
  • For position coordinates, 6 decimal places is typically sufficient
  • For rotation matrices, verify orthogonality (R * R^T should be close to identity)

TypeScript Path Resolution#

Galatea uses per-library path mappings in tsconfig.base.json rather than a wildcard. If a new library's imports fail to resolve, check that the specific mapping has been added:

json
{
  "@galatea/new-library": ["libs/galatea/new-library/src/index.ts"]
}

Build Order Failures#

If a library fails to build because a dependency is not yet built, verify:

  1. implicitDependencies is set in the failing library's project.json
  2. "dependsOn": ["^build"] is present in the build target
  3. The dependency library's project.json is valid

Nx Cache Issues#

bash
pnpm nx reset

Viewing the Dependency Graph#

bash
pnpm nx graph --focus=@galatea/core

This visualizes the full dependency tree from core through all application layers.


Quick Reference#

Action Command
Install dependencies pnpm install
Build one library pnpm nx build @galatea/<lib>
Build all Galatea libraries pnpm nx run-many --target=build --projects=tag:scope:galatea
Test one library pnpm nx test @galatea/<lib>
Test all Galatea libraries pnpm nx run-many --target=test --projects=tag:scope:galatea
Lint one library pnpm nx lint @galatea/<lib>
Lint all Galatea libraries pnpm nx run-many --target=lint --projects=tag:scope:galatea
Reset Nx cache pnpm nx reset
View dependency graph pnpm nx graph --focus=@galatea/core