Picodev Lab

Decode a ready logic capture of the session (browser or bench). protocol "uart" with channels {rx} and options {baud (300-1000000, 9600), bits (5-9, 8), parity (none, even, odd), stop (1, 2), invert (false)}; "spi" with {sck, mosi?, miso?, cs?} (one data pin at least) and options {mode (0-3, 0), bit_order (msb, lsb), bits (8)}; "i2c" with {scl, sda}. channels are pins of the capture. Returns {capture, protocol, frames, next, problems}, 2000 frames from offset. uart frames {t_us, value, error?} (framing, parity) and text, the printable bytes of the page; spi {t_us, mosi?, miso?} per word, while cs is low when given; i2c {t_us, kind (start, restart, address, data, stop), value?, rw?, ack?}. problems: what makes the decoding doubtful.

The setups: status available (open_session works) or soon (listed, cannot be opened yet), their modes (free, challenge) and their benches by kind (status open, or soon: not offered yet).

Takes no parameters.

Create a session (mode: free or challenge). Give open_url to the human: nothing simulates until they open it in their browser.

Replace the code in the human's browser and, if run, compile it in the lab's cloud and start it. The fallback of push_program: use it only when the toolchain to compile locally is missing (no arduino-cli, core or library).

Send a program compiled on the visitor's machine (Intel HEX text, 48 KiB at most, e.g. arduino-cli's <sketch>.ino.hex) to the human's browser, which loads it in the simulator without compiling and, if run, starts it. files: the sources, shown read-only in the editor, never compiled. During a turn on a real bench, the bench gets it too. Prefer it to push_to_editor, which is the fallback when the local toolchain is missing.

Last state (with circuit, the browser's components and wires), last compilation and the events after since_ms (2000 at most). `serial` is the full serial output of the current run (up to 16 KiB), reset at each compile and NOT starved by pin events: prefer it over reconstructing serial from `events`. During a turn on a real bench, `serial` and the serial events come from the bench's board (since the turn began or the last compile), `t` on the turn's clock. In challenge mode: the level's brief and its results. circuit_modified: the circuit differs from the setup sheet's (types, ids, properties, wires; not positions or colours), null when unknown. circuit_error: the editor's last refusal of a pushed circuit, returned once.

Change the visibility (private, link, public). Returns the viewer link; current viewers are disconnected.

Take a place in the queue for benches of this kind (for example real or sim). The browser must be connected.

The session's place: state none, waiting (position, estimated wait eta_s) or turn (bench, end of the turn ends_at, Unix seconds).

Give back the place in the queue, or the turn if it has started.

End the session now, as when it expires: the place or turn ends, viewers and the browser are disconnected, everything is forgotten.

The session's state without its events, cheap enough to poll: browser connected (owner), visibility, current viewer link (not renewed), viewers, created_at and expires_at (Unix seconds), run (compilations so far: event times restart at each), level and levels (null in free mode), capture ({id, kind, state} of the session's capture, logic or analog, or null). Not reported to the human's journal.

Challenge mode: propose `value` as the answer of the current level's test `test` (an answer test of the level's brief). One answer per second at most. The hub checks it and returns {test, ok}; the verdict is also shown in the bench. For a hint, ask the visitor to reveal one in the bench.

Challenge mode: move to the next level, as the bench's "Next level" button, and only when it would be offered: every test of the current level passed and a next level exists. Returns {level, levels}, the new level (index); session_status's level changes with the bench's next state. No level skipping.

Record every edge of the requested pins (probes of the setup sheet; by default the logic ones) for duration_ms (1 to 10 000 ms). In the browser's simulation, in simulated time; during the session's turn on a real bench, at the bench's logic analyser, in real time (no browser or running simulation needed then). trigger {pin, edge}: pin among pins, edge rising, falling or any; the recording then lasts wait_ms + duration_ms (10 000 ms at most) and keeps pre_ms (0 to wait_ms) before the first matching edge within wait_ms and duration_ms after it; with no such edge, the whole recording. Read the result with read_capture, decode it with decode_capture.

Sample the voltage of 1 to 4 board pins (the board's own numbers: Nano A0-A7 = 14-21, Uno A0-A5 = 14-19, Mega A0-A15 = 54-69; by default the setup's scope probes) at rate_hz (100 to 10 000) for duration_ms (1 to 10 000 simulated ms), 200 000 samples at most in all. An ADC input reads the voltage the circuit applies; any other pin, its logic level times the supply (PWM shows as a square wave). Simulation only: refused during a turn on a real bench, whose analyser has no analog channel. Read the result with read_capture.

State of a capture (recording, ready, failed) and its kind (logic, analog). Once ready, the measures per pin and, for a logic capture, the edges [t_us, pin, v], 2000 from offset; for an analog one, rate_hz and the samples, rows [mv_1, ...] in the order of pins (row k at k / rate_hz), 2000 rows from offset. next: the following offset, or null. t0_ms: the first sample on the session's clock (ms since the simulation's launch, or since the start of the turn on a real bench), null when unknown; t_us and rows count from the capture's start. format="png": the same without edges or samples, plus a chart of the signals as an image (from_ms and to_ms, from the capture's start, to zoom; 4 per minute).

A served setup sheet (setup.json, files included; never a solution): board, components and wires (circuit), probes, levels (without their hints: hints come through read_simulation as the visitor reveals them). Plus, when it exists, schema.png, the starting circuit as the editor draws it, as an image.

Free mode only: replace the circuit in the human's browser (the simulation stops). components: [{type, id, properties, x?, y?}] (the board is not a component), wires: [{id, start: {componentId, pinName}, end: {...}, color?, waypoints?: [{x, y}] (the wire's route, 16 points at most)}], in the shape of the setup sheet's circuit; 40 components, 120 wires, 48 KiB. The editor checks types and pins: read the outcome with read_simulation (circuit, circuit_error). 6 per minute.

During the session's turn on a real bench: a photo of the bench, as an image, and t_ms, the instant of the photo in ms since the start of the turn (null when unknown). One every 2 seconds.

Draft the specification of the visitor's own project with Picodev's interview: you ask the visitor, this tool says what to ask next and makes the PDF. Nothing is sent and nothing is kept. Call it with the sections written so far (none at first). sections: {id: text in simple Markdown}, ids envelope, fonctionPrincipale, fonctions, alimentation, format, environnement, production, preferences, 4000 characters at most each. sections.contact, optional: the contact details the visitor wants printed at the end of the document (1000 characters at most; not part of the interview's progress). language: fr or en, the one the visitor answers in (headings, look_for and questions, the PDF). pdf=true: also the PDF, with Picodev Lab's template; requires title (one line). figures, with pdf=true, optional: the drawings the visitor approved, 3 at most, each {section (a section id), caption (one line), type (png or svg), data (base 64, 200 KiB at most decoded)}, placed after their section's text; an SVG loads nothing (no script, no DTD, href # or data:image/ only). Returns {rules (how to run the interview: follow them), sections [{id, heading, required, state (empty, thin, filled), look_for and questions while not filled}], next (the section to ask about, or null), ready (the four required sections filled: enough for Picodev to start), filename and pdf (base 64) with pdf=true}.

Send Picodev the specification of the visitor's project, as a PDF, or only return its preview (send=false). sections: {id: text in simple Markdown}, ids envelope, fonctionPrincipale, fonctions, alimentation, format, environnement, production, preferences (the 8 sections of a product specification), 4000 characters at most each; a missing section reads "À préciser" (to be specified). send=false: preview, nothing is sent, contact and consent are not required. send=true: requires contact {name, email, company?, phone?} and consent=true. nda=true: the visitor wants a non-disclosure agreement first; without sections, only contact and title are sent, without PDF. session and agent_token, optional: the mail also says what the visitor did in the lab. language: fr or en, the PDF's headings. sections.contact and figures: as for spec_draft (refused with nda=true, as sections). Write the sections with spec_draft first. Before passing consent=true, show the visitor the consent text in the visitor's language, and wait until they accept it. In French: "J'accepte que mes coordonnées et la description de mon projet soient envoyées à Picodev par courriel, pour qu'ils me répondent. Picodev les garde 3 ans après le dernier échange et ne les utilise pour rien d'autre. Détails : lab.picodev.fr/confidentialite" In English: "I agree that my contact details and the description of my project are sent to Picodev by e-mail, so that they can answer me. Picodev keeps them for 3 years after our last exchange and uses them for nothing else. Details: lab.picodev.fr/en/privacy" Returns {sent, filename, pdf (base 64, absent with nda), missing (empty or too short sections), next (a sentence for the visitor, to say in their language)}}: write the PDF on the visitor's machine.

Send Picodev a meeting request. contact: {name, email, company?, phone?}. context: the project in a few sentences (2000 characters at most): what the visitor wants to do, where they stand, what they did in the lab. availabilities: 1 to 10 slots {from, to}, ISO 8601 dates with a time zone, within the next 60 days; or {text}, one sentence ("Tuesday mornings"). Requires consent=true. session and agent_token, optional: the mail also says what the visitor did in the lab. Before passing consent=true, show the visitor the consent text in the visitor's language, and wait until they accept it. In French: "J'accepte que mes coordonnées et la description de mon projet soient envoyées à Picodev par courriel, pour qu'ils me répondent. Picodev les garde 3 ans après le dernier échange et ne les utilise pour rien d'autre. Détails : lab.picodev.fr/confidentialite" In English: "I agree that my contact details and the description of my project are sent to Picodev by e-mail, so that they can answer me. Picodev keeps them for 3 years after our last exchange and uses them for nothing else. Details: lab.picodev.fr/en/privacy" Returns {sent, next}: Picodev answers by e-mail to confirm a slot.