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"
}
| Field | What it is |
|---|---|
esasim.kind | Always "project": how EsaSim recognises the folder. |
name, description | Shown in the project list. |
type | The 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 isws-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:
backendfor a worker block (Python,backend.py),frontendfor a view (JavaScript,frontend.js). - outputs:
tablecarries a CSV,resultreceives the dict thatrunreturns. 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:
cpuruns on any worker. Usenvidia,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
idof your choice (used by the edges), the block'stype(a built-in id or yourws-id), an optionaltitle, a position (x,y; leave them out and EsaSim places the blocks), andparamsfor the settings you change from their defaults. - edges go from an output port to an input port:
sweep › tableinto the chart's and the table'sdatainput,sweep › resultinto the metrics view. - Every built-in block, with its ports, settings and defaults, is in the block reference. The chart's
xandyare column names of the CSV.
5. Push and import
git add .
git commit -m "Gusty landing: sweep and wind study"
git push
- In EsaSim, open Projects > New project > Import a project.
- 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.
- 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 pullbefore 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
secretis 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
- Write a view in JavaScript, with live values and a button that talks back to the running block: Blocks that work together.
- Call the published blueprint from your own code, with its settings as inputs: From a blueprint to your app and Endpoints.
- Everything a block can do with
ctx: Custom blocks.