FIELD ships understanding a handful of senses — touch, tilt, light, sound, and more. A plugin teaches it one more chip, without changing FIELD itself.
This guide picks up after Your First FIELD. It assumes you already know the four words — Actor, Role, Cue, Mechanism — and have wired at least one real sensor to a board.
By the end you will have written, installed, and tested one small plugin file — for a sensor chip of your choice.
A plugin adds a new hardware option to a sense FIELD already has (TOUCH, LIGHT, SOUND…). It never invents a brand‑new kind of sense. A plugin for a new touch chip makes the TOUCH role smarter — it does not create a "TOUCH_2" role type.
No install step, no build, no code review, nothing to compile. A plugin is a single file that ends in .field-plugin.json — plain text you could write in Notes.
Inside the file you describe three things: which role the chip belongs to (TOUCH, LIGHT, SOUND…), how to wire it (which pin goes where), and a few short fragments of Arduino code that read the chip and hand FIELD a number from 0 to 1.
One new hardware option inside an existing role — like a new item in a dropdown.
A short human‑readable line — "VCC → 5V | GND → GND | OUT → A0" — shown to whoever wires the board.
Every plugin has the same shape: a few lines describing the plugin, then a list of components — usually just one, for your one chip.
my-sensor.field-plugin.json
{
// Always the number 1. Tells FIELD which plugin format this is.
"fieldPluginVersion": 1,
// A name only you use, in reverse order, like a website address backwards.
"id": "com.yourname.mysensor",
"name": "My Sensor",
"version": "1.0.0",
"author": "Your Name",
"description": "One line: what it reads and why someone would want it",
"components": [ /* one entry per chip — see next chapter */ ]
}id nobody else will pick — your name plus a short word for the sensor.See "com.jordan.tmp36" or similar.description. This is the only line most people will read before installing.See it shown in the Plugin Manager's "Installed" list.components empty for now — the next chapter fills it in.See a file that is valid but does nothing yet.FIELD only checks the shape of these fields, not their meaning — there is no review queue, no approval wait. That is what makes "write it, install it, test it" possible in one sitting. It also means: double‑check your own file, nobody else will.
Most beginner sensors — a photoresistor, a sound module, a soil moisture probe, a potentiometer — work the same way: power, ground, and one wire that outputs a voltage FIELD reads with analogRead(). Start there before touching I2C chips.
This example teaches the LIGHT role about a photoresistor module. The pattern is the same for any single‑wire analog sensor — only the role, name, and wording change.
photoresistor.field-plugin.json
{
"fieldPluginVersion": 1,
"id": "com.yourname.photoresistor",
"name": "Photoresistor Module",
"version": "1.0.0",
"author": "Your Name",
"description": "3-pin analog light sensor module (LDR + resistor on a breakout board)",
"components": [
{
"roleId": "LIGHT",
"kind": "input",
"id": "photoresistor",
"name": "Photoresistor Module",
"description": "Higher light = higher value. Wire OUT to any analog pin.",
"wiring": "VCC → 5V | GND → GND | OUT → analog pin",
"codegen": {
"loopRead": " fieldSend(\"{{roleEventKey}}\", analogRead({{pin}}) / 1023.0f);"
}
}
]
}roleId: "LIGHT" — this chip is teaching the LIGHT role a new trick, not inventing a new sense.See it appear inside LIGHT's own hardware list, next to any built‑in options.wiring is just a sentence a human reads while holding a screwdriver. Write it the way you would tell a friend.See the exact text shown in the Actor panel once installed.codegen.loopRead is one line of real Arduino code, run every loop. {{pin}} and {{roleEventKey}} are filled in automatically by FIELD — you never hand‑type a pin number here.See this exact line appear inside the generated sketch.Copy the file above into a text editor. Change id, name, and description to match a sensor you actually own. If it is analog and single‑wire, that loopRead line usually works unchanged.
Some chips need more than one wire and one line — they talk over I2C, need a library, or have a setting like an address or a channel number. The shape grows, but stays the same idea.
Arduino library names FIELD installs before compiling — e.g. "libraries": ["Adafruit_MPR121"].
A dropdown or number field shown in the Actor panel — like an I2C address, or which of 12 electrodes to read.
excerpt — an I2C touch chip with a setting
"noMainPin": true,
"libraries": ["Adafruit_MPR121"],
"extraConfig": [
{ "key": "electrode", "label": "Electrode (0–11)",
"type": "number", "default": 0 }
],
"codegen": {
"includes": ["<Wire.h>", "<Adafruit_MPR121.h>"],
"globals": "Adafruit_MPR121 mpr_{{varName}};",
"setup": " mpr_{{varName}}.begin();",
"loopRead": " fieldSend(\"{{roleEventKey}}\", mpr_{{varName}}.touched() & (1<<{{cfg.electrode}}) ? 1.f : 0.f);"
}Whatever you type as {{cfg.electrode}} above is whatever the person using your plugin picked in that number field — filled in the same way {{pin}} is. noMainPin: true means "this chip has no single main pin" (it uses two fixed I2C wires instead).
FIELD's own MPR121 plugin uses every feature described here — includes, a global variable, setup code, a config dropdown, and two components on two different roles in one file. It ships with FIELD as a working reference, not just documentation.
A plugin installs into the canvas you already have open. There is no separate build or restart.
.field-plugin.json file anywhere onto the window.See the text land in the box, or a drop message while dragging.{{roleEventKey}} matches the role your codegen sends — a copy‑paste from a different role is the most common mistake.The format itself was already about as small as a hardware‑description file can get: one JSON file, no build step, no eval, three ways to load it in. The friction we found was smaller and more specific — the blank page.
The Paste JSON box in the Plugin Manager started empty. You had to go find an example somewhere else and copy it in by hand.
A "Start from a template →" link fills the box with a minimal working analog‑sensor skeleton — the same shape as Chapter 3's example — so the first edit is changing three words, not writing from nothing.
We kept the format itself untouched rather than adding a wizard or form‑builder on top of it. A form would hide the JSON shape instead of teaching it — and the JSON shape is also exactly what an AI coding assistant needs to generate a whole plugin for you from one sentence like "I have a DHT22 temperature sensor," if you'd rather not hand‑write one at all.
Point an AI coding assistant at FIELD's repo and ask it to write the plugin for your exact chip, using AI-PLUGINS.md as its reference. It follows the same rules this guide just taught you — just faster.
You wrote a plugin, installed it, and watched a real number move. That is the whole system — everything else in this guide was detail.
extraConfig field if your chip has a setting — an address, a channel, a range..field-plugin.json file with anyone who owns the same chip — it is the whole install, nothing else needed.← Back to Your First FIELD · Connect two things · FIELD home