16 Development Environments: Selection and Setup Evidence
16.1 Start With the Decision
A toolchain that works on one laptop is not yet a project environment. Setup, versions, and a clean build must be easy to prove.
16.2 Route Overview
This is part 1 of 2. Continue with Development Environments: Reproducibility and Debugging.
16.3 Part Objectives
- Select a development environment from prototype needs.
- Define setup and clean-build evidence for a toolchain.
16.4 Chapter Roadmap
- In 60 Seconds
- Start With the Story
- Environment Choice Guides Proof
- Reproducible Setup First
- Hidden Local State Misleads
- The Environment Is Part of the Evidence
- Avoid Tool-First Selection
- Selection Criteria
- Choose Environment by Evidence
- Concept Check: Clean Build Evidence
- Environment Families
16.5 Start With the Story
Two learners can write the same sensor sketch and get different results because their board package, compiler, library version, upload tool, serial monitor, or simulator setup is different. The environment is part of the prototype, not a background detail. If it is invisible, the evidence cannot travel.
This chapter starts from that practical problem. Choose the simplest environment that exposes the current risk, then record enough detail for another person to rebuild, upload, observe, and challenge the result without guessing which machine made it work.
16.6 Environment Choice Guides Proof
The environment decides what the team can rebuild, upload, observe, and hand off. A fast editor helps only if the build path and debugging evidence can be repeated by someone else.
Inspect What must and Dependencies in Figure 16.1 for environment choice guides proof. To place environment choice guides proof on firm evidence, compare What must with Dependencies in it. The figure ties this to discard, escalate.
Read What must with Dependencies in Figure 16.1 for environment choice guides proof. Work through it from the What must field to Dependencies, then the discard, escalate disposition. Combining What must with Dependencies hides accountability. This supplies environment choice guides proof with a concrete retest point.
For IoT prototypes, environment choice also decides how much board-specific behavior is visible: pin maps, clock setup, flash partitioning, RAM pressure, driver versions, simulator gaps, upload mode, and live logs. An Arduino IDE sketch may be enough to prove first contact with an ESP32 or Nano 33 IoT board, but it is weak evidence if nobody records the selected board package, library source, upload port, serial speed, and example configuration.
As the prototype moves beyond first contact, the environment should expose more of the risk. A PlatformIO project can pin board profiles and libraries in the repository. ESP-IDF can make partition tables, sdkconfig options, FreeRTOS settings, and monitor output explicit. Zephyr with west can show board overlays, devicetree bindings, Kconfig choices, and a repeatable build command. A host harness can test payload parsing or retry-state logic before scarce hardware is available, while Wokwi, Renode, QEMU, or vendor simulators can speed iteration only when their hardware limits are clearly stated.
For example, a cold-room sensor prototype may need a board package record, BME280 library version, I2C pin map, serial capture, and one temperature-step log before the team can trust the reading path. A pump controller may need the upload method, watchdog reset log, and relay-disable observation before reviewers discuss architecture style. In both cases, the environment proves a narrow claim and names the claims it does not yet prove.
The best choice is therefore not the most advanced tool. It is the lightest environment that exposes the current evidence question and leaves a record that later language, architecture, library, testing, OTA, and best-practice chapters can reuse.
16.7 Reproducible Setup First
Record the environment while the prototype is still changing. The notes should be specific enough for a reviewer to recreate the same firmware path from a clean checkout.
- Target profile: board name, MCU/runtime, board package, compiler, language version, memory assumptions, and enabled peripherals.
- Build path: exact command, dependency lock source, configuration file, generated-output boundary, and expected artifact location.
- Upload and observe path: programmer, boot mode, cable or network path, serial speed, debugger setup, log capture, and reset procedure.
- Boundary notes: what the simulator, REPL, CI runner, or vendor SDK cannot prove until the real target is tested.
For a first sensor run, this record may be short: board selection, library version, upload command, serial monitor settings, one normal log, and the unproven conditions such as battery current, enclosure temperature, and RF range. For a team prototype, it should become a repository artifact: platformio.ini, sdkconfig, CMakeLists.txt, Zephyr overlay files, dependency lockfiles or version notes, build scripts, and a README section that states how to rebuild and observe the device.
Match the environment to the current review question. Use Arduino IDE, Thonny, or a vendor starter project when the evidence is first board contact. Move to PlatformIO, ESP-IDF, STM32CubeIDE, nRF Connect SDK, Zephyr west, or a CMake-based project when dependency control, multi-file structure, board variants, or team review matters. Add OpenOCD, J-Link, Ozone, pyOCD, serial captures, logic-analyzer traces, or power-profiler notes when the problem is timing, reset cause, memory corruption, interrupt handoff, or power state.
Keep secrets out of the environment record. It should name where credentials come from, such as a local environment file, GitHub Actions secret, lab token, or provisioning fixture, without storing keys, certificates, passwords, production endpoints, or private device identities. A repeatable environment is valuable only when it is also safe to share with reviewers.
16.9 Learning Objectives
By the end of this chapter, you will be able to:
- Define what evidence a software development environment must leave for an IoT prototype.
- Match environment families to prototype stage, board risk, language risk, team workflow, and debugging need.
- Record board profiles, build inputs, dependency versions, configuration, and upload commands without exposing secrets.
- Decide when a simulator, REPL, vendor SDK, project-based toolchain, or CI build adds useful evidence.
- Write a handoff record that lets the next software chapter continue from a reproducible environment.
16.10 The Environment Is Part of the Evidence
The previous chapter treated software prototypes as evidence. This chapter focuses on the environment that creates that evidence. If another engineer cannot rebuild, upload, inspect, and challenge the prototype, the environment is still incomplete.
Start with the prototype question, then choose the environment that makes the answer visible:
“Which IDE should we use?” is too early. Ask what must be proven: a first board blink, a sensor driver, a multi-board abstraction, a power state, a crash recovery path, or a repeatable team build. The right environment depends on the evidence question.
16.11 Selection Criteria
No development environment is best for every IoT prototype. Use criteria that reviewers can observe instead of relying on tool preference.
16.12 Choose Environment by Evidence
The environment decision should be repeatable enough that two reviewers would choose the same starting point from the same evidence need.
First, Name the prototype question. Write the narrow claim the next run must support, such as “the ESP32-S3 board can read the BME280 over I2C,” “the payload parser rejects malformed JSON,” or “the Zephyr build still fits in the selected flash partition.”. Next, Pick the lightest environment that exposes that question. Use Arduino IDE, Thonny, or a starter vendor example for first contact; PlatformIO, ESP-IDF, STM32CubeIDE, Zephyr west, or nRF Connect SDK when board profiles, dependencies, and multi-file builds matter; and host tests or simulators when the question is logic rather than physics. Then, Record the path from source to observation. Capture source revision, board profile, dependency versions, build command, upload command, serial or debugger command, expected output, and the part of the result that remains unproven. After that, Retest when the risk changes. A clean serial demo does not prove sleep current, OTA rollback, RF range, secure boot, or field recovery. Move to the next environment only when it reveals evidence the current one cannot.
16.13 Concept Check: Clean Build Evidence
16.14 Environment Families
It is safer to think in environment families than to memorize a fixed ranking of named tools. Specific products change, but the evidence role stays stable.
Inspect First contact and Production risk in Figure 16.2 for environment families. To make environment families reviewable, locate First contact beside Production risk on it. The figure ties this to Starter.
Read First contact with Production risk in Figure 16.2 for environment families. Compare it with First contact and Production risk as cases under Starter. Neither First contact nor Production risk wins without Starter. That is the review order required by environment families.
16.15 Continue to the Next Part
Carry this evidence into Development Environments: Reproducibility and Debugging, which begins with Incremental Examples.