EPICS → Experimental Physics and Industrial Control System
A documentation-only guide to the EPICS ecosystem: what every tool is, why it exists, where to get it, and how a real facility wires them together.
If you already know EPICS, the official intro is probably where you want to be. If you read that page and thought "okay, but what do I actually install, and in what order?" — you're in the right place.
📖 Read it as a website: https://nusaqib.github.io/EPICS-for-Dummies/
EPICS is not one program. It is a collaboration-maintained ecosystem of a couple of hundred separately released pieces — a core library, dozens of device-support modules, half a dozen GUI toolkits, several archivers, alarm servers, directory services, gateways, and client libraries in six languages. Nobody hands you the list. Every facility rediscovers it.
This repo is that list, organised so you can find your way:
| If you… | Go to |
|---|---|
| have never heard of a "process variable" | Start Here |
| want to understand how the pieces fit | Architecture |
| are looking for the tool that does X | The Toolbox — the catalogue |
| need to get software running on a box | Build & Install |
| want to see a whole facility designed end-to-end | Example Facility |
| need a command, a record field, an env var | Reference |
| have an error message and no idea what it means | Error Message Index |
| have just joined a facility | Your First Week |
There is no code in this repository — no install scripts, no IOC templates. Everything here points at upstream projects maintained by people who know their own software better than a shell script in a beginner's guide ever will. Commands appear inline in the how-to pages so you can read them before you run them.
Abstract architecture diagrams only get you so far. So this guide designs a complete, fictional facility and shows every decision:
🔬 The Helios Light Source (HLS) — a hypothetical 3 GeV, 4th-generation synchrotron light source with a linac, a booster, a 528 m storage ring, and 20 beamlines.
The Example Facility section works through its machine parameters, PV naming convention, ~330 IOCs, network segmentation, service deployment, archiver sizing arithmetic, alarm hierarchy, machine protection boundaries, and a beamline — then closes with operations scenarios and a laptop-scale simulation of the whole thing.
HLS is invented. Its numbers are plausible and internally consistent, in the spirit of published 4th-generation light source design reports, but it is a teaching device — not a design you should build.
- What is EPICS? — the 10-minute version
- Core Concepts — PVs, records, IOCs, CA/PVA
- Build EPICS Base → Your First IOC
- Command Cheat Sheet — poke at it with
caget/caput/camonitor - Talk to a Real Device — one instrument, end to end
- Architecture Overview — now the layer model will mean something
- The Toolbox — browse; you don't need it all
- Example Facility — see it assembled at scale
Or skip straight to a prebuilt training VM if you'd rather click than compile.
Corrections, dead links, and "you forgot tool X" are all welcome — see CONTRIBUTING.md. A monthly CI job checks every external link in this repo, but link rot outruns automation.
MIT. The linked projects carry their own licences; check them before you deploy anything.
This guide is written by someone learning EPICS, not by the EPICS core developers. It is a map, not an authority. Where this repo and docs.epics-controls.org disagree, the official documentation is right and this is out of date. Accuracy & Known Uncertainties says which parts are solid, which are a learner's best understanding, and lists the specific claims most worth an expert's twenty minutes. Nothing here is safety-related guidance: EPICS is a control and monitoring system, not a safety system, and no page in this repo should be used to design a personnel-protection or machine-protection interlock. See Machine Protection for why that line matters.