Picodev Lab

The available setups, their modes (free, challenge) and their benches.

{
  "type": "object",
  "properties": {},
  "title": "list_setupsArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "list_setupsOutput"
}

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

{
  "type": "object",
  "properties": {
    "setup": {
      "title": "Setup",
      "type": "string"
    },
    "mode": {
      "title": "Mode",
      "type": "string"
    }
  },
  "required": [
    "setup",
    "mode"
  ],
  "title": "open_sessionArguments"
}

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).

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "files": {
      "items": {
        "$ref": "#/$defs/File"
      },
      "title": "Files",
      "type": "array"
    },
    "run": {
      "default": true,
      "title": "Run",
      "type": "boolean"
    }
  },
  "required": [
    "session",
    "agent_token",
    "files"
  ],
  "$defs": {
    "File": {
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "content": {
          "title": "Content",
          "type": "string"
        }
      },
      "required": [
        "name",
        "content"
      ],
      "title": "File",
      "type": "object"
    }
  },
  "title": "push_to_editorArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "push_to_editorOutput"
}

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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "hex": {
      "title": "Hex",
      "type": "string"
    },
    "files": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/File"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Files"
    },
    "run": {
      "default": true,
      "title": "Run",
      "type": "boolean"
    }
  },
  "required": [
    "session",
    "agent_token",
    "hex"
  ],
  "$defs": {
    "File": {
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "content": {
          "title": "Content",
          "type": "string"
        }
      },
      "required": [
        "name",
        "content"
      ],
      "title": "File",
      "type": "object"
    }
  },
  "title": "push_programArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "push_programOutput"
}

Last state (with circuit, the browser's components and wires), last compilation and the events after since_ms (2000 at most). 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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "since_ms": {
      "default": 0,
      "title": "Since Ms",
      "type": "number"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "read_simulationArguments"
}

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

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "visibility": {
      "title": "Visibility",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token",
    "visibility"
  ],
  "title": "set_visibility_toolArguments"
}

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

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "kind": {
      "title": "Kind",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token",
    "kind"
  ],
  "title": "queue_join_toolArguments"
}

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

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "queue_statusArguments"
}

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

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "queue_leave_toolArguments"
}

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

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "close_sessionArguments"
}

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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "session_statusArguments"
}

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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "next_levelArguments"
}

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). Read the result with read_capture.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "pins": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pins"
    },
    "duration_ms": {
      "default": 1000,
      "title": "Duration Ms",
      "type": "integer"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "capture_logicArguments"
}

Sample the voltage of 1 to 4 board pins (0-13 digital, 14-21 = A0-A7; 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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "pins": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pins"
    },
    "duration_ms": {
      "default": 1000,
      "title": "Duration Ms",
      "type": "integer"
    },
    "rate_hz": {
      "default": 10000,
      "title": "Rate Hz",
      "type": "integer"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "capture_analogArguments"
}

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).

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "capture": {
      "title": "Capture",
      "type": "string"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "format": {
      "default": "json",
      "title": "Format",
      "type": "string"
    },
    "from_ms": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Ms"
    },
    "to_ms": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Ms"
    }
  },
  "required": [
    "session",
    "agent_token",
    "capture"
  ],
  "title": "read_captureArguments"
}

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

{
  "type": "object",
  "properties": {
    "id": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "read_setup_publicArguments"
}

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?}], 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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    },
    "components": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Components",
      "type": "array"
    },
    "wires": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Wires",
      "type": "array"
    }
  },
  "required": [
    "session",
    "agent_token",
    "components",
    "wires"
  ],
  "title": "push_circuitArguments"
}

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": [
    "result"
  ],
  "title": "push_circuitOutput"
}

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.

{
  "type": "object",
  "properties": {
    "session": {
      "title": "Session",
      "type": "string"
    },
    "agent_token": {
      "title": "Agent Token",
      "type": "string"
    }
  },
  "required": [
    "session",
    "agent_token"
  ],
  "title": "bench_snapshotArguments"
}

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}.

{
  "type": "object",
  "properties": {
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Title"
    },
    "sections": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sections"
    },
    "language": {
      "default": "fr",
      "title": "Language",
      "type": "string"
    },
    "pdf": {
      "default": false,
      "title": "Pdf",
      "type": "boolean"
    },
    "figures": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Figure"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Figures"
    }
  },
  "$defs": {
    "Figure": {
      "properties": {
        "section": {
          "title": "Section",
          "type": "string"
        },
        "caption": {
          "title": "Caption",
          "type": "string"
        },
        "type": {
          "title": "Type",
          "type": "string"
        },
        "data": {
          "title": "Data",
          "type": "string"
        }
      },
      "required": [
        "section",
        "caption",
        "type",
        "data"
      ],
      "title": "Figure",
      "type": "object"
    }
  },
  "title": "spec_draftArguments"
}

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.

{
  "type": "object",
  "properties": {
    "title": {
      "title": "Title",
      "type": "string"
    },
    "contact": {
      "anyOf": [
        {
          "$ref": "#/$defs/Contact"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "sections": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sections"
    },
    "nda": {
      "default": false,
      "title": "Nda",
      "type": "boolean"
    },
    "consent": {
      "default": false,
      "title": "Consent",
      "type": "boolean"
    },
    "send": {
      "default": true,
      "title": "Send",
      "type": "boolean"
    },
    "session": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Session"
    },
    "agent_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Token"
    },
    "language": {
      "default": "fr",
      "title": "Language",
      "type": "string"
    },
    "figures": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Figure"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Figures"
    }
  },
  "required": [
    "title"
  ],
  "$defs": {
    "Contact": {
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "email": {
          "title": "Email",
          "type": "string"
        },
        "company": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Company"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Phone"
        }
      },
      "required": [
        "name",
        "email"
      ],
      "title": "Contact",
      "type": "object"
    },
    "Figure": {
      "properties": {
        "section": {
          "title": "Section",
          "type": "string"
        },
        "caption": {
          "title": "Caption",
          "type": "string"
        },
        "type": {
          "title": "Type",
          "type": "string"
        },
        "data": {
          "title": "Data",
          "type": "string"
        }
      },
      "required": [
        "section",
        "caption",
        "type",
        "data"
      ],
      "title": "Figure",
      "type": "object"
    }
  },
  "title": "brief_submitArguments"
}

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.

{
  "type": "object",
  "properties": {
    "contact": {
      "$ref": "#/$defs/Contact"
    },
    "context": {
      "title": "Context",
      "type": "string"
    },
    "availabilities": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        }
      ],
      "title": "Availabilities"
    },
    "consent": {
      "title": "Consent",
      "type": "boolean"
    },
    "session": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Session"
    },
    "agent_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Token"
    }
  },
  "required": [
    "contact",
    "context",
    "availabilities",
    "consent"
  ],
  "$defs": {
    "Contact": {
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "email": {
          "title": "Email",
          "type": "string"
        },
        "company": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Company"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Phone"
        }
      },
      "required": [
        "name",
        "email"
      ],
      "title": "Contact",
      "type": "object"
    }
  },
  "title": "request_meetingArguments"
}