# kempf09/sense-grip architecture

> Architecture diagram of the GitHub repository kempf09/sense-grip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kempf09/sense-grip
- Repository: https://github.com/kempf09/sense-grip

## Overview

SENSE-GRIP is ESP32-S3 gripper firmware operated through a web dashboard. The user configures and opens the jaw, calibrates force sensors, then arms it; ToF detection starts a state-machine grip, while FSR contact and force guide grasping and safety trips lead to FAULT. The control task owns command dispatch, sensor sampling, and servo actions. The README documents additional dashboard diagnostics, calibration, filtering, jogging, and safety behavior. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled implementation details are not asserted.

Main entry points: [`SenseGrip/control.cpp`](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/control.cpp) (Control task), [`SenseGrip/web.cpp`](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web.cpp) (HTTP API), [`SenseGrip/fsr.cpp`](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr.cpp) (FSR acquisition), [`SenseGrip/web_pages.h`](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web_pages.h) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_web["HTTP API<br/>[web.cpp]"]
  node_ui["Dashboard UI<br/>[web_pages.h]"]
end

subgraph group_control["Grip control"]
  node_controller["Control task<br/>[control.cpp]"]
  node_fsm["Grip state machine<br/>[fsm_core.cpp]"]
  node_config["Runtime settings<br/>[config_core.cpp]"]
  node_configstore[("Config persistence<br/>[config.cpp]")]
end

subgraph group_sensing["Sensing"]
  node_fsr["FSR acquisition<br/>[fsr.cpp]"]
  node_filter["Force filters<br/>[fsr_filter.cpp]"]
  node_force["Force and contact math<br/>[fsr_math.cpp]"]
  node_tof["ToF acquisition<br/>[tof.cpp]"]
  node_tofdetect["Object detection<br/>[tof_detect.cpp]"]
end

subgraph group_actuation["Servo actuation"]
  node_servo["Servo control<br/>[servo.cpp]"]
  node_protocol["Servo protocol<br/>[servo_proto.cpp]"]
end

node_operator(("Operator"))
node_gripper{{"Gripper hardware"}}

node_operator -->|"operates"| node_ui
node_ui -->|"sends requests"| node_web
node_web -->|"queues commands"| node_controller
node_web -->|"reads snapshots"| node_controller
node_controller -->|"steps"| node_fsm
node_controller -->|"applies settings"| node_config
node_controller -.->|"loads settings"| node_configstore
node_controller -->|"samples"| node_fsr
node_fsr -->|"filters samples"| node_filter
node_fsr -->|"computes force"| node_force
node_controller -->|"sets detection"| node_tof
node_tof -->|"detects objects"| node_tofdetect
node_controller -->|"polls and moves"| node_servo
node_fsm -->|"returns motor action"| node_controller
node_controller -->|"reads and actuates"| node_gripper
node_servo -->|"uses packet codec"| node_protocol
node_protocol -->|"exchanges packets"| node_gripper

click node_web "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web.cpp"
click node_ui "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web_pages.h"
click node_controller "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/control.cpp"
click node_fsm "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsm_core.cpp"
click node_config "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/config_core.cpp"
click node_configstore "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/config.cpp"
click node_fsr "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr.cpp"
click node_filter "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr_filter.cpp"
click node_force "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr_math.cpp"
click node_tof "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/tof.cpp"
click node_tofdetect "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/tof_detect.cpp"
click node_servo "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/servo.cpp"
click node_protocol "https://github.com/kempf09/sense-grip/blob/main/SenseGrip/servo_proto.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_ui toneBlue
class node_controller,node_fsm,node_config,node_configstore toneAmber
class node_fsr,node_filter,node_force,node_tof,node_tofdetect toneMint
class node_servo,node_protocol toneRose
class node_operator,node_gripper toneIndigo
```

## Components

### Dashboard

- [HTTP API](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web.cpp): `SenseGrip/web.cpp`
- [Dashboard UI](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/web_pages.h): `SenseGrip/web_pages.h`

### Grip control

- [Control task](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/control.cpp): `SenseGrip/control.cpp`
- [Grip state machine](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsm_core.cpp): `SenseGrip/fsm_core.cpp`
- [Runtime settings](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/config_core.cpp): `SenseGrip/config_core.cpp`
- [Config persistence](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/config.cpp): `SenseGrip/config.cpp`

### Sensing

- [FSR acquisition](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr.cpp): `SenseGrip/fsr.cpp`
- [Force filters](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr_filter.cpp): `SenseGrip/fsr_filter.cpp`
- [Force and contact math](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/fsr_math.cpp): `SenseGrip/fsr_math.cpp`
- [ToF acquisition](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/tof.cpp): `SenseGrip/tof.cpp`
- [Object detection](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/tof_detect.cpp): `SenseGrip/tof_detect.cpp`

### Servo actuation

- [Servo control](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/servo.cpp): `SenseGrip/servo.cpp`
- [Servo protocol](https://github.com/kempf09/sense-grip/blob/main/SenseGrip/servo_proto.cpp): `SenseGrip/servo_proto.cpp`

### Other components

- **Operator**
- **Gripper hardware**

## Connections

- Operator → Dashboard UI: operates (evidence: `README.md`)
- Dashboard UI → HTTP API: sends requests (evidence: `SenseGrip/web.cpp`)
- HTTP API → Control task: queues commands (evidence: `SenseGrip/web.cpp`)
- HTTP API → Control task: reads snapshots (evidence: `SenseGrip/web.cpp`)
- Control task → Grip state machine: steps (evidence: `SenseGrip/control.cpp`)
- Control task → Runtime settings: applies settings (evidence: `SenseGrip/control.cpp`)
- Control task → Config persistence: loads settings
- Control task → FSR acquisition: samples (evidence: `SenseGrip/control.cpp`)
- FSR acquisition → Force filters: filters samples
- FSR acquisition → Force and contact math: computes force
- Control task → ToF acquisition: sets detection (evidence: `SenseGrip/control.cpp`)
- ToF acquisition → Object detection: detects objects (evidence: `SenseGrip/tof.cpp`)
- Control task → Servo control: polls and moves (evidence: `SenseGrip/control.cpp`)
- Grip state machine → Control task: returns motor action
- Control task → Gripper hardware: reads and actuates (evidence: `README.md`)
- Servo control → Servo protocol: uses packet codec
- Servo protocol → Gripper hardware: exchanges packets (evidence: `README.md`)
