Stage 12 · Lesson 15/16

Robot Simulation & Digital Twin · Lesson 15

Building a Complete Digital Twin

Est. 60–75 min

Why

Why this lesson matters

Lessons 1–14 built every layer: the model, physics, sensors, controllers, the ROS 2 bridge, commands and tests. A digital twin puts them together and connects them to the real robot. The twin receives real data, stays close to the real arm, and tells you when the real arm starts to behave differently.

You will see why a model without data drifts, calibrate the twin from recorded data, detect a fault from the gap between twin and reality, and see what late data does. On the bench, the UNO runs a tiny twin of one joint and raises an alarm when your “real” joint stops following it.

Concept

Model + live data + comparison = twin

1. Simulation, digital shadow, digital twin

Wikipedia describes a digital twin as a computational model of a real product or system (the physical twin) used for simulation, testing, monitoring and maintenance. It also notes that a model running without data from its physical counterpart is only loosely called a twin. A common distinction: in a digital shadow, data flows one way, from the real asset to the model; in a digital twin, data flows both ways and the twin can also send commands back.

Wikipedia (Digital twin) also lists twin prototype, twin instance (one per real unit) and twin aggregate (many instances together).
Data real → modelData model → realExample
SimulationnonoLessons 6–14 on their own
Digital shadowyesnoRViz showing /joint_states from the real arm
Digital twinyesyesTwin checks commands, predicts, and can stop the real arm
Black-and-white photo looking down into an Apollo Command Module simulator with three astronauts in spacesuits and helmets at the instrument panel
Three astronauts in the Apollo Command Module Simulator, 1968. Wikipedia notes NASA used simulators to evaluate the Apollo 13 oxygen-tank failure — an early twin-like use of a model alongside the real mission.Photo: NASA · Public domain · Source: Wikimedia Commons · resized, converted to WebP

2. The layers of your arm’s twin

  • Model: URDF links, joints and limits (Lessons 2–5).
  • Physics and contact: mass, inertia, friction (Lessons 6–9).
  • Sensors: encoders and IMU with noise (Lesson 10).
  • Controllers: the same control loop as the real arm (Lesson 11).
  • Bridge and messages: /joint_states in, commands out, on one clock (Lessons 12–13).
  • Tests: the suite that must pass before commands go to the real arm (Lesson 14).
  • New in this lesson: calibration from real data, live sync and a residual monitor.

3. Calibrate, sync, compare

Calibrate: record the real arm for a while, then choose the model values (gain, friction, offset) that make the twin match best — the smallest squared error. Always check on new data you did not fit on. Sync: regularly set the twin’s state to the latest real measurement, so small errors do not pile up. Compare: just before each sync, the twin predicted where the joint would be; the difference is the residual. Healthy arm → small residual. Something changes (loose coupling, worn gear, extra load) → residual grows → alarm.

Black-and-white photo of five men in shirts and ties gathered around a console with papers in NASA Mission Control
Mission Control during the Apollo 13 oxygen-cell failure, 1970. Engineers compared what the spacecraft reported with what they expected — the same idea as a twin’s residual.Photo: NASA · Public domain · Source: Wikimedia Commons · resized, converted to WebP

Visual

Visualise it: the layers of a twin

The layers of a twin: model, world, physics, sensors, bridge, controller, vision/IK/trajectory and mission. Toggle layers, set the sync gap and run a test scenario. (Educational explorer, not a live plant twin.)

Interactive · Digital twin explorer · Educational approximation

Digital twin stack layersSimulation-based testing

Twin completeness: 100% · sync gap 15%

Select a scenario and Run test.

Stack composes Stages 7–11 conceptually. Maps to Gazebo / Isaac / Webots / MuJoCo stacks — no engine install. Not a live plant digital twin platform.

Code lab

Code lab: calibrate, sync and watch a twin

twin_sync_lab.py simulates a “real” joint whose true gain, friction and encoder offset are hidden from the twin, plus sensor noise. It compares a design-value twin, fits the twin to 20 s of recorded data, runs live sync with a residual alarm while a fault appears at t = 6 s, and shows the effect of late data. All values are examples. Run python3 twin_sync_lab.py (about 2 seconds).

twin_sync_lab.py · Python
"""Complete digital twin lab (Stage 12, Lesson 15) - Python 3 stdlib only.

A "real" joint (hidden from the twin: weaker motor, extra friction, encoder offset,
noise) and its digital twin (our simulation model) get the same commands.
  1. Model only (no data): how far does the twin drift from the real joint?
  2. Calibrate the twin from recorded data (least squares) -> drift shrinks
  3. Live sync + residual monitor: a fault at t = 6 s (loose coupling) -> alarm
  4. Late data: what a 0 / 50 / 200 ms delay does to the twin's picture
All numbers are EXAMPLES for a desk-arm joint, simulated at 100 Hz.
"""
import math, random

DT = 0.01
def command(t):                       # a repeating pick motion, radians
    return 0.8 * math.sin(0.6 * t) + (0.4 if (t % 5) < 2.5 else -0.4)

def step(q, cmd, gain, fric):
    v = gain * (cmd - q)              # simple position loop: speed ~ error
    v = v - fric if v > fric else (v + fric if v < -fric else 0.0)
    return q + v * DT

REAL = dict(gain=3.2, fric=0.06, offset=0.03)   # the twin does NOT know these
def run_real(T, fault_at=None, seed=15):
    rng, q, out = random.Random(seed), 0.0, []
    for k in range(int(T / DT)):
        t = k * DT
        g = REAL["gain"] * (0.35 if fault_at and t >= fault_at else 1.0)   # loose coupling
        q = step(q, command(t), g, REAL["fric"])
        out.append((t, command(t), q + REAL["offset"] + rng.gauss(0, 0.004)))   # encoder reading
    return out

def run_twin(data, gain, fric, offset, sync=False):
    q, err = data[0][2] - offset, []
    for t, cmd, meas in data:
        if sync and int(round(t / DT)) % 10 == 0:
            q = meas - offset                     # pull the twin to the real state at 10 Hz
        pred = q + offset
        err.append(meas - pred)
        q = step(q, cmd, gain, fric)
    return err

def rms(e): return math.sqrt(sum(x * x for x in e) / len(e))

print("=== 1. Model only (design values, no real data) ===")
data = run_real(20)
e = run_twin(data, gain=4.0, fric=0.0, offset=0.0)
print(f"design twin (gain 4.0, no friction, no offset): RMS gap {math.degrees(rms(e)):.2f} deg, "
      f"worst {math.degrees(max(map(abs, e))):.2f} deg")
print("-> a model that never sees real data is only a simulation, not a twin.")

print()
print("=== 2. Calibrate from 20 s of recorded data ===")
best = None
for g10 in range(20, 51):                                   # search gain 2.0..5.0
    for f100 in range(0, 13):                               # friction 0..0.12
        for o1000 in range(-50, 51, 5):                     # offset -0.05..0.05
            e = run_twin(data, g10 / 10, f100 / 100, o1000 / 1000)
            s = sum(x * x for x in e)
            if best is None or s < best[0]:
                best = (s, g10 / 10, f100 / 100, o1000 / 1000)
_, G, F, O = best
e = run_twin(data, G, F, O)
print(f"fitted: gain {G}, friction {F}, offset {O}   (hidden truth: 3.2, 0.06, 0.03)")
print(f"calibrated twin: RMS gap {math.degrees(rms(e)):.2f} deg, worst {math.degrees(max(map(abs, e))):.2f} deg")
fresh = run_real(20, seed=99)
e2 = run_twin(fresh, G, F, O)
print(f"check on NEW data (other seed): RMS gap {math.degrees(rms(e2)):.2f} deg")
print("-> always check calibration on data you did not fit on.")

print()
print("=== 3. Live sync + residual alarm (fault at t = 6.00 s) ===")
faulty = run_real(12, fault_at=6.0)
THRESH, NEED = math.radians(1.0), 3
for label, d in (("healthy", run_real(12, seed=7)), ("loose coupling", faulty)):
    res = run_twin(d, G, F, O, sync=True)
    checks = [(d[k][0], res[k]) for k in range(9, len(d), 10)]   # twin's 0.1 s-ahead prediction error, just before each sync
    run, alarm = 0, None
    for t, r in checks:
        run = run + 1 if abs(r) > THRESH else 0
        if run >= NEED and alarm is None:
            alarm = t
    worst = max(abs(r) for _, r in checks)
    print(f"{label:>15}: worst 0.1 s prediction error {math.degrees(worst):.2f} deg, alarm "
          + (f"at t = {alarm:.2f} s" if alarm else "none"))
print("-> residual = real - twin prediction. Small when healthy; it grows when the real")
print("   joint stops behaving like the model. Alarm needs > 1 deg on 3 checks in a row (no flicker).")

print()
print("=== 4. Late data ===")
for delay_ms in (0, 50, 200):
    n = delay_ms // 10
    lag = [abs(data[k][2] - data[k - n][2]) for k in range(max(n, 1), len(data))]
    print(f"state arrives {delay_ms:3d} ms late: twin shows the joint up to "
          f"{math.degrees(max(lag)):.2f} deg away from where it really is")
print("-> stamp every message (Lesson 12) and let the twin predict forward by the delay.")

Output (run with python3 twin_sync_lab.py)

=== 1. Model only (design values, no real data) ===
design twin (gain 4.0, no friction, no offset): RMS gap 3.20 deg, worst 7.25 deg
-> a model that never sees real data is only a simulation, not a twin.

=== 2. Calibrate from 20 s of recorded data ===
fitted: gain 3.3, friction 0.06, offset 0.03   (hidden truth: 3.2, 0.06, 0.03)
calibrated twin: RMS gap 0.34 deg, worst 1.75 deg
check on NEW data (other seed): RMS gap 0.34 deg
-> always check calibration on data you did not fit on.

=== 3. Live sync + residual alarm (fault at t = 6.00 s) ===
        healthy: worst 0.1 s prediction error 0.73 deg, alarm none
 loose coupling: worst 0.1 s prediction error 10.02 deg, alarm at t = 6.29 s
-> residual = real - twin prediction. Small when healthy; it grows when the real
   joint stops behaving like the model. Alarm needs > 1 deg on 3 checks in a row (no flicker).

=== 4. Late data ===
state arrives   0 ms late: twin shows the joint up to 0.00 deg away from where it really is
state arrives  50 ms late: twin shows the joint up to 7.97 deg away from where it really is
state arrives 200 ms late: twin shows the joint up to 26.62 deg away from where it really is
-> stamp every message (Lesson 12) and let the twin predict forward by the delay.

Try it: switch twin layers on and off and watch the completeness score. Pick a scenario and press “Run test”. With Noisy sensors, move the sync gap slider above 40% to see the twin fail. (Educational explorer, not a live plant twin.)

Interactive · Digital twin explorer · Educational approximation

Digital twin stack layersSimulation-based testing

Twin completeness: 100% · sync gap 15%

Select a scenario and Run test.

Stack composes Stages 7–11 conceptually. Maps to Gazebo / Isaac / Webots / MuJoCo stacks — no engine install. Not a live plant digital twin platform.

Bench build: a one-joint twin on the UNO

twin_mirror.ino runs a twin of one joint. Pot A0 is the command. The twin moves towards it at a fixed 1.5 rad/s, like a servo would. Pot A1 is the real joint — you turn it by hand to follow. Every 50 ms the UNO compares them. Fall more than 0.25 rad behind for 0.5 s and the red ALARM LED lights. Type c to calibrate the offset between the pots, s to re-sync the twin.

Signals only — no motors. When you later connect a real servo arm, power the servos from a separate 5–6 V supply with a common ground, never from a GPIO pin, and make the twin’s ALARM stop the motion.
PartConnectionNote
Pot 1 — commandouter legs 5V/GND, wiper A0where the joint should go
Pot 2 — real jointouter legs 5V/GND, wiper A1turn by hand to follow
Green LED + 220 ΩD5 → resistor → LED → GNDtwin and real agree
Red LED + 220 ΩD6 → resistor → LED → GNDALARM
twin_mirror.ino · Arduino C++
// twin_mirror.ino - Stage 12, Lesson 15: Building a Complete Digital Twin
// The UNO runs a tiny digital twin of one joint and compares it with the "real"
// joint every 50 ms.
//   Pot A0 = COMMAND (where the joint should go)
//   Pot A1 = REAL joint position - you turn it by hand to follow the command
//   The twin model moves towards the command at a fixed speed (like a servo).
//   residual = real - twin. If it stays above 0.25 rad for 10 checks (0.5 s) -> ALARM.
//   Serial 'c' = calibrate: measure the average real-vs-twin offset over 1 s and remove it.
//   Serial 's' = sync: snap the twin to the real position (like re-syncing from /joint_states).
//
// Wiring (no motors):
//   Pot 1: outer legs 5V/GND, wiper A0 (command)
//   Pot 2: outer legs 5V/GND, wiper A1 (real joint)
//   Green LED + 220 ohm on D5 -> GND : in sync
//   Red LED + 220 ohm on D6 -> GND   : ALARM (twin and real disagree)
// Serial Monitor 115200, line ending "Newline".

const float RANGE_RAD = 270.0 * DEG_TO_RAD;   // example 270 degree pots
const float TWIN_SPEED = 1.5;                 // rad/s - the twin's model of the joint
const float THRESH = 0.25;                    // rad
const int NEED = 10;                          // checks in a row
const unsigned long STEP_MS = 50;

float twin = 0, offset = 0;
int over = 0;
bool alarm = false;
unsigned long last = 0;

float readRad(int pin) { return (analogRead(pin) / 1023.0 - 0.5) * RANGE_RAD; }

void calibrate() {
  Serial.println(F("CALIBRATE: hold both pots still for 1 s"));
  float sum = 0;
  for (int i = 0; i < 20; i++) { sum += readRad(A1) - twin; delay(50); }
  offset = sum / 20;
  Serial.print(F("offset = ")); Serial.print(offset, 3); Serial.println(F(" rad"));
}

void setup() {
  Serial.begin(115200);
  pinMode(5, OUTPUT);
  pinMode(6, OUTPUT);
  twin = readRad(A1);
  Serial.println(F("twin_mirror: c = calibrate offset, s = sync twin to real"));
}

void loop() {
  if (Serial.available()) {
    char ch = Serial.read();
    if (ch == 'c') calibrate();
    if (ch == 's') { twin = readRad(A1) - offset; over = 0; alarm = false; Serial.println(F("SYNC")); }
  }
  if (millis() - last < STEP_MS) return;
  last += STEP_MS;

  float cmd = readRad(A0);
  float maxStep = TWIN_SPEED * STEP_MS / 1000.0;
  float d = cmd - twin;
  twin += constrain(d, -maxStep, maxStep);     // the twin's model: limited speed

  float real = readRad(A1) - offset;
  float residual = real - twin;
  over = fabs(residual) > THRESH ? over + 1 : 0;
  if (over >= NEED && !alarm) { alarm = true; Serial.println(F("ALARM: real joint is not behaving like the twin")); }
  if (over == 0 && alarm) { alarm = false; Serial.println(F("back in sync")); }
  digitalWrite(5, alarm ? LOW : HIGH);
  digitalWrite(6, alarm ? HIGH : LOW);

  static int n = 0;
  if (++n % 10 == 0) {                          // print twice a second
    Serial.print(F("cmd=")); Serial.print(cmd, 2);
    Serial.print(F(" twin=")); Serial.print(twin, 2);
    Serial.print(F(" real=")); Serial.print(real, 2);
    Serial.print(F(" residual=")); Serial.println(residual, 3);
  }
}
Serial Monitor (115200, Newline) — example session, your values will differ · Text
twin_mirror: c = calibrate offset, s = sync twin to real
cmd=0.01 twin=0.01 real=0.04 residual=0.030
> c
CALIBRATE: hold both pots still for 1 s
offset = 0.031 rad
cmd=0.82 twin=0.53 real=0.41 residual=-0.120
cmd=0.82 twin=0.82 real=0.79 residual=-0.030
cmd=-1.20 twin=0.07 real=0.62 residual=0.550
ALARM: real joint is not behaving like the twin
cmd=-1.20 twin=-1.20 real=-1.15 residual=0.050
back in sync
A small grey control building with a gravel yard under dark clouds, with wind turbines on the horizon
The control building at Camster Wind Farm. Wind turbines are watched remotely; comparing live data with what is expected is how problems are spotted early.Photo: Peter Moore · CC BY-SA 2.0 · Source: Wikimedia Commons · resized, converted to WebP

Debugging

SymptomLikely causeFix
Twin slowly drifts away from the real armno sync, or model values wrongSync from /joint_states regularly; calibrate
Constant residual even when stillencoder or zero offsetCalibrate the offset at a known pose
Many false alarmsthreshold too tight, noise, or bad modelRequire several readings in a row; improve the model; then tune threshold
Twin looks behind during fast movesdata delayStamp messages; predict forward by the delay; reduce latency
Calibration great on old data, bad on newover-fitting one recordingFit on one recording, check on another
Bench: ALARM never clearstwin and pot far apart after a long gapSend s to re-sync

Real world

Digital twins in the real world

  • Manufacturing: Wikipedia describes twins fed by sensor data from machines for process monitoring — for example, force data showing whether a friction-stir weld has enough contact.
  • Space: NASA used simulators alongside real missions, including to evaluate the Apollo 13 failure.
  • Energy and buildings: twins are used to monitor and coordinate plants, grids and building systems.
  • Your lab: a twin of the 6DOF desk arm that shows live joint states, predicts each move, checks commands with the test suite, and raises an alarm when the real arm stops behaving like the model.

Think

Think about it

Think

Your twin raises an ALARM on joint3 every afternoon around 3 PM, but the arm seems fine. What could be happening, and how would you find out?

Experiment

Try it in the lab

About 60 minutes. Python 3 for the script; an Arduino UNO, two pots, two LEDs and two 220 Ω resistors for the bench.

Experiment

Build, calibrate and break a twin

You will need

  • `twin_sync_lab.py` (Python 3, no libraries)
  • Digital twin explorer (in your browser)
  • Arduino UNO, two 10 kΩ pots, green and red LEDs, two 220 Ω resistors

Steps

  1. Run `twin_sync_lab.py`. Change the hidden REAL friction to 0.09. Does calibration find it? What is the new RMS gap?
  2. In part 3, change the fault strength from 0.35 to 0.8 (a smaller fault). Is it still detected? How quickly?
  3. Change the alarm rule to need 1 check instead of 3. Does the healthy run now give a false alarm?
  4. Bench: follow the command slowly, then quickly, then stop following. Note the residual and when the alarm comes.
  5. Bench: skip calibration, then use `c`. How does the resting residual change?
  6. Interactive: turn off “ROS bridge” and run Nominal pick. Explain the result in one sentence.

Interactive · Digital twin explorer · Educational approximation

Digital twin stack layersSimulation-based testing

Twin completeness: 100% · sync gap 15%

Select a scenario and Run test.

Stack composes Stages 7–11 conceptually. Maps to Gazebo / Isaac / Webots / MuJoCo stacks — no engine install. Not a live plant digital twin platform.

A twin is only as good as its model and its data. Calibrate from real data, check on new data, sync often, compare with a residual, and alarm on a pattern, not one reading.

Knowledge check

Check your understanding

Knowledge check

1. What makes a digital twin different from a plain simulation?

2. In a digital shadow, data flows…

3. Why check calibration on new data?

4. The residual is…

5. Why need several readings over the threshold before an alarm?

6. In the script, a loose coupling appears at t = 6.00 s. The alarm comes at…

7. Joint states arrive 200 ms late during fast moves. The twin…

Mini assignment

Hands-on assignment

Mini assignment

A working twin plan for your desk arm

Bring all the Stage 12 layers together into one twin of your 6DOF desk arm and show it catching a problem.

Deliverables

  • A one-page diagram of your twin: every layer, which lesson it came from, and every data flow (real → twin, twin → real) with topic names.
  • A calibration report for at least one joint: fitted values, RMS gap on the fitting data and on new data.
  • A residual monitor with a written alarm rule, and a log showing it catching a fault you made on purpose (in the script or on the bench).
  • Bench log from `twin_mirror.ino` showing calibration, normal following, ALARM and back in sync.

Do this, step by step

  1. Draw your twin: every layer, the lesson it came from, and every data flow with topic names.
  2. Run twin_sync_lab.py and read the fitted gain, friction and offset.
  3. Check the RMS gap on new data, not only on the fitting data.
  4. Write an alarm rule for the residual monitor and make a fault on purpose to test it.
  5. Bench: run twin_mirror.ino and log calibration, normal following, ALARM and back in sync.

Stuck? Hints, one at a time

NoteTry the task first. Read one hint, try again, and only then read the next one.
  1. The script’s REAL values are hidden from the twin. Compare your fit to them only at the end.
  2. A good fit on old data but a bad one on new data means the model is copying noise.
  3. An alarm rule needs a size and a time, for example “residual over X for Y samples”.

Challenges (pick by level)

  • 🟢 Beginner: Draw your twin’s layer diagram and label which are a digital shadow (one-way) and which would make it a full twin (two-way).
  • 🟡 Intermediate: In twin_sync_lab.py, make the twin predict forward by the delay in part 4 and show how much the error shrinks.
  • 🟠 Advanced: Write a Python script that reads twin_mirror.ino output over serial, plots real, twin and residual live, and saves a CSV.
  • 🔴 Expert: Build an rclpy node that subscribes to /joint_states from your arm (or Gazebo), runs a calibrated model of each joint, publishes residuals and an alarm topic.
  • ⚫ Research: Read the Wikipedia article on digital twins and its references on twin prototype, instance and aggregate. Design how an aggregate of 20 desk arms in a lab could predict which arm needs maintenance first.

Next step

You now have every piece. In Lesson 16 — Capstone: Build & Test a Simulated 6DOF Robot you will build the complete simulated 6DOF arm, test it, and use it as the twin of your real desk arm.

Look back: Lesson 14: Simulation-Based Testing. Next: Lesson 16: Capstone — Build & Test a Simulated 6DOF Robot. Related: Stage 10 — ROS 2.

Sources

Self-attested for now — keep artifacts in your lab notebook.

Complete

Today's goal

0 of 1 done today

0-day streak
Daily goal:lessons, quizzes or assignments a day

Mark this lesson complete when you have worked the experiment, knowledge check, and assignment (even roughly).

Stuck somewhere?

Ask a doubt about this lesson

Saved with this lesson's id and your email so we can reply. Privacy · or email contact@aihubstation.in