Esacode

Docs / Tutorials

Tutorial: a project in code

Build a project as files in your own editor: a worker block in Python, a blueprint in JSON, pushed to GitHub, imported, run, and improved with git.

This tutorial builds a whole project as files, in your own editor, with git: a worker block in Python, the blueprint that wires it to three views, and the file that says what the project is. You push them to GitHub, EsaSim takes them in, and from then on you can change the code in your editor or in EsaSim; both sides stay in step. It is the same project you would build in the blueprint editor or with an AI assistant, written by hand.

The question it answers: how strong can the wind get before a drone misses a moving landing pad? Every file below was imported and run as written.

Before you start

  • GitHub linked to your EsaSim account (Profile > GitHub, or the setup after signing up).
  • One worker paired, with Run code from projects on. No GPU is needed: the block uses only Python's standard library. See Set up a worker.
  • git, an editor, and Python 3 if you want to try the block on your computer first.

The files of a project

A project is a folder (usually a repository of its own) with these files. EsaSim reads nothing else, so the repository can also hold your notes, notebooks or tests.

gusty-landing/
├── project.json                      what the project is
├── README.md                         its first page in EsaSim
├── blueprints/
│   └── wind-study.json               a blueprint: blocks and connections
└── blocks/
    └── ws-gusty-landing-sweep/       a block of your workspace
        ├── block.json                its ports and settings
        └── backend.py                its code (a view has frontend.js)

Built-in blocks (Chart, Table, the 3D view…) are not copied into the project: a blueprint names them by id. Only blocks of your own workspace, whose ids start with ws-, travel with it.

1. Make the repository

Make an empty private repository on GitHub, for example gusty-landing, then:

git clone https://github.com/<you>/gusty-landing.git
cd gusty-landing
mkdir -p blueprints blocks/ws-gusty-landing-sweep

2. project.json

{
  "esasim": { "kind": "project" },
  "name": "Gusty landing",
  "description": "A drone landing on a moving pad, swept over wind speeds.",
  "type": "drones",
  "readme": "README.md"
}
FieldWhat it is
esasim.kindAlways "project": how EsaSim recognises the folder.
name, descriptionShown in the project list.
typeThe kind of project, for its icon and filters: robotics, drones, autonomous-vehicles, research… Optional.
readme"README.md" to use that file as the project's first page. Without it, EsaSim writes one from the blueprints.

Write a short README.md next to it: one line saying what question the project answers is enough.

3. The worker block

block.json: its ports and settings

In blocks/ws-gusty-landing-sweep/block.json:

{
  "id": "ws-gusty-landing-sweep",
  "name": "Gusty landing sweep",
  "category": "Simulation",
  "icon": "wind",
  "side": "backend",
  "summary": "Lands a drone on a moving pad in rising wind, many times per wind speed.",
  "help": "For each wind speed from 0 to Max wind, runs Trials landings with random gusts and counts those that touch down within the pad's radius.",
  "inputs": [],
  "outputs": [
    { "id": "table", "label": "Landings by wind", "type": "table", "formats": ["csv"] },
    { "id": "result", "label": "Summary", "type": "metrics", "formats": ["json"] }
  ],
  "params": [
    { "key": "max_wind", "label": "Max wind (m/s)", "type": "number", "default": 14, "min": 1, "max": 60 },
    { "key": "steps", "label": "Wind speeds", "type": "number", "default": 15, "min": 2, "max": 200 },
    { "key": "trials", "label": "Trials per speed", "type": "number", "default": 50, "min": 1, "max": 10000 },
    { "key": "pad_speed", "label": "Pad speed (m/s)", "type": "number", "default": 1, "min": 0, "max": 10 },
    { "key": "pad_radius", "label": "Pad radius (m)", "type": "number", "default": 0.5, "min": 0.1, "max": 5 },
    { "key": "seed", "label": "Random seed", "type": "number", "default": 1 }
  ],
  "hardware": ["cpu"]
}
  • The id is ws- and the name in lowercase with dashes: Gusty landing sweep is ws-gusty-landing-sweep. Use the same id for the folder and in the blueprint. If a block of your workspace already has that id, the import gives it a new version; if the id does not match the name, EsaSim makes the block under the id that does and says so in the import window.
  • side: backend for a worker block (Python, backend.py), frontend for a view (JavaScript, frontend.js).
  • outputs: table carries a CSV, result receives the dict that run returns. Every worker block also has a Live telemetry output you do not declare. Port types and settings are listed in Custom blocks.
  • params are the settings people change in the blueprint; the code reads them from ctx.params.
  • hardware: cpu runs on any worker. Use nvidia, amd… for GPU code.

backend.py: the code

import random


def land(wind, gust, pad_speed, rng):
    """One landing, sideways (x) and down (z): returns how far from the pad's centre it touched down, in metres."""
    dt = 0.05
    x, vx = rng.uniform(-2.0, 2.0), 0.0         # start a little off to the side
    z = 20.0                                     # 20 m up
    pad = 0.0
    gust_now = 0.0
    while z > 0.0:
        gust_now += (rng.gauss(0.0, gust) - gust_now) * 0.2      # gusts change smoothly
        drift = 0.12 * (wind + gust_now)                         # wind pushes the drone sideways
        error = pad - x
        ax = 1.6 * error + 2.4 * (pad_speed - vx)                # the controller follows the pad
        ax = max(-4.0, min(4.0, ax))                             # within what the motors can do
        vx += (ax + drift) * dt
        x += vx * dt
        z -= 1.5 * dt                                            # 1.5 m/s down
        pad += pad_speed * dt
    return abs(x - pad)


def run(ctx):
    max_wind = float(ctx.params.get("max_wind", 14))
    steps = int(ctx.params.get("steps", 15))
    trials = int(ctx.params.get("trials", 50))
    pad_speed = float(ctx.params.get("pad_speed", 1.0))
    radius = float(ctx.params.get("pad_radius", 0.5))
    rng = random.Random(int(ctx.params.get("seed", 1)))

    rows = []
    for i in range(steps):
        wind = max_wind * i / max(1, steps - 1)
        misses = [land(wind, 0.35 * wind, pad_speed, rng) for _ in range(trials)]
        ok = sum(1 for m in misses if m <= radius)
        rows.append({"wind_mps": round(wind, 2), "success_rate": round(ok / trials, 3),
                     "mean_miss_m": round(sum(misses) / trials, 3)})
        ctx.telemetry("sweep", rows[-1])                         # live values while it runs
        ctx.progress(100 * (i + 1) // steps, f"wind {wind:.1f} m/s")

    with open(ctx.output("table", "landings.csv"), "w") as f:
        f.write("wind_mps,success_rate,mean_miss_m\n")
        for r in rows:
            f.write(f"{r['wind_mps']},{r['success_rate']},{r['mean_miss_m']}\n")

    failing = [r["wind_mps"] for r in rows if r["success_rate"] < 0.9]
    return {                                                     # the "result" output (result.json)
        "landings": steps * trials,
        "success_rate": round(sum(r["success_rate"] for r in rows) / steps, 3),
        "fails_from_mps": failing[0] if failing else None,
    }

It lands the drone trials times at each wind speed, writes one row per speed to landings.csv on the table output, sends each row live while it runs, and returns a summary. Packages it imports are installed on the worker by themselves; this one needs none.

Try it on your computer first

A worker block is a plain Python function, so you can run it without EsaSim with a stand-in for ctx. Save this as try_block.py anywhere outside the project:

# try_block.py: run backend.py on your computer, without EsaSim
import json, os, sys, importlib.util

spec = importlib.util.spec_from_file_location("block", sys.argv[1])
block = importlib.util.module_from_spec(spec)
spec.loader.exec_module(block)


class Ctx:
    params = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}

    def output(self, port, name):
        path = os.path.join("out", port, name)
        os.makedirs(os.path.dirname(path), exist_ok=True)
        return path

    def telemetry(self, channel, data):
        print("live", channel, data)

    def progress(self, pct, note=""):
        pass


print(json.dumps(block.run(Ctx()), indent=2))
python3 try_block.py blocks/ws-gusty-landing-sweep/backend.py '{"steps": 5}'

It prints the summary and writes out/table/landings.csv. When it works here, it works on the worker.

4. The blueprint

In blueprints/wind-study.json: the sweep, and three built-in views that show its outputs.

{
  "name": "Wind study",
  "description": "Where does the landing start to fail as the wind rises?",
  "graph": {
    "nodes": [
      { "id": "sweep", "type": "ws-gusty-landing-sweep", "x": 0, "y": 0,
        "params": { "max_wind": 14, "steps": 15, "trials": 50 } },
      { "id": "chart", "type": "chart", "title": "Success by wind", "x": 320, "y": -80,
        "params": { "kind": "line", "x": "wind_mps", "y": "success_rate", "title": "Success rate by wind (m/s)" } },
      { "id": "table", "type": "table-view", "title": "All speeds", "x": 320, "y": 80 },
      { "id": "summary", "type": "metrics-view", "title": "Summary", "x": 320, "y": 240 }
    ],
    "edges": [
      { "from": { "node": "sweep", "port": "table" },  "to": { "node": "chart",   "port": "data" } },
      { "from": { "node": "sweep", "port": "table" },  "to": { "node": "table",   "port": "data" } },
      { "from": { "node": "sweep", "port": "result" }, "to": { "node": "summary", "port": "data" } }
    ]
  }
}
  • nodes: each has an id of your choice (used by the edges), the block's type (a built-in id or your ws- id), an optional title, a position (x, y; leave them out and EsaSim places the blocks), and params for the settings you change from their defaults.
  • edges go from an output port to an input port: sweep › table into the chart's and the table's data input, sweep › result into the metrics view.
  • Every built-in block, with its ports, settings and defaults, is in the block reference. The chart's x and y are column names of the CSV.

5. Push and import

git add .
git commit -m "Gusty landing: sweep and wind study"
git push
  1. In EsaSim, open Projects > New project > Import a project.
  2. Under From GitHub, give the repository and choose Work on it together: the project saves back to this repository, so your editor and EsaSim share it.
  3. The import window lists each step: it read one blueprint and one workspace block, made the block Gusty landing sweep, made the project and added the blueprint Wind study. A file EsaSim cannot read is named there, with the reason.

Open the project's Blueprint tab: the four blocks are on the grid, wired. The sweep's code opens with a double-click, exactly as you wrote it.

6. Run it

Press Run. The block goes to your worker, the chart fills in by wind speed while it runs, and the summary shows when it ends: with the default settings the drone lands almost every time up to 6 m/s (98% at 6), and the success rate falls apart at 7 m/s.

The reason is in the controller: it only reacts to how far the drone is from the pad and how fast it moves, so a steady wind leaves it off to the side, a little more for each m/s.

7. Change the code, push again

Add an integral term, which builds up while the drone stays off to the side and cancels the steady push of the wind. In backend.py:

    gust_now = 0.0
    integral = 0.0                                               # new
    while z > 0.0:
        ...
        error = pad - x
        integral += error * dt                                   # new
        ax = 1.6 * error + 2.4 * (pad_speed - vx) + 0.8 * integral

Raise the range to see where it fails now: in the blueprint file, set the sweep's "max_wind": 30 and "steps": 16. Then:

git commit -am "Integral term; sweep up to 30 m/s"
git push

Open the project in EsaSim: This project changed on GitHub: taking the changes in. The block gets a new version, the blueprint's draft is replaced, and nothing else changes. Run again: the drone now lands every time up to 26 m/s and starts to miss at 28 m/s.

Both runs stay under Runs, each with the version of the blueprint that made it, so the comparison is between two things on record.

Working from both sides

  • Changes made in EsaSim are commits too. When you change a setting or code in the editor, EsaSim commits it to the same repository. Run git pull before you edit locally.
  • Both sides changed? EsaSim merges them blueprint by blueprint and asks only about what was changed in two different ways. See Working together on GitHub.
  • Keys never go in the repository. A setting of type secret is pasted in EsaSim and stays there; the blueprint file has it empty.
  • Results stay out of git. Outputs live on the workers and in EsaSim; what a blueprint trains is published as a GitHub release only when you choose.

Next