Software Specification V0.6
Overview
- ROS 2 for orchestration and internal communication
- Headless Ubuntu as the embedded operating system
- DRM/KMS for direct projector control
- OpenCV for image processing <Planned>
- C++ for hardware interactions
- Systemd for boot, supervision, and recovery.
The software is responsible for coordination of robotic components, files, and data transforms for all tools. Currently the exposure tool is the only one supported.
The exposure tool has a very simple interface, expose this image for some period of time. However the generation of that image is the trick. To handle this it is useful to think of it in five steps:
IR = intermediate Representation
Normalization takes what ever form it was in to a standard intermediate form. This intermediate form is very limited because the pattern (what is exposed) is only black or white. At preparation a transform is associated with it that will align it with the top left corner of the frame. Then the final computing step is to rasterize it, it is at this point the projector calibration is taken into account.
Each step generates an artifact (A tracked file) stating what effects it applied and storing a reference to its dependencies. A artifact can not be changed after being stored. (generation of a prepared IR is not considered a distinct step)
A job is a single distinct action. All Jobs go through the orchestrator, at this time the only type of job is an exposure job but this is planned to be expanded.
There are also two useful organizational units:
- A preparation group is a group of IR that all have a single common transform, this is useful for when needing multilayer alignment EX: in a multi layer PCB.
- A job sequence is a sequence of jobs that have to be done in order. The use case here is if you wanted to test different exposure lengths you could create a array of preparations and jobs then instruct the exposure tool to expose them one after another. This is also going to be expanded to encompass multi tool coordination.
Test Patterns
To calibrate the exposure tool, several different test patterns can be exposed, they are the following:
- Working area outline - requires 4 corners
- Display corners - requires 4 corners
- Full Black
- Full White
- Checkerboard - requires a checkerboard size in pixels
It is not possible to adjust the brightness of a test pattern.
pcb_renderer owns test-pattern generation, IR encoding, and rasterization. pcb_orchestrator handles test parameters, archive calls, and exposure lifetime. pcb_orchestrator does not interpret or create IR payloads.
Glossary:
- IR: A consistent intermediate representation. Has a tag of what step created it.
- Normalized Representation: The immediate conversion of a source file into IR with no transforms applied
- Preparation: IR & Transform dictating how the IR should align with the working area.
- Prepared IR: A Normalized IR that has had a preparation transform applied.
- Pattern: The final rasterized image. Cab bit gave a calibration id
- Working area: The physical area that the project can expose over
- Work Coordinate: Coordinates relative to the tool zero, by convention for the exposure tool is top top left with increasing X being to the right and increasing Y being downwards
Packages
pcb_archive
Is responsible for tracking all artifacts. This will subscribe to pcb_orchestrator/Health/* and record each post to the health record when received.
When artifacts are listed it is the artifact envelope that is given.
| End point | Type | Purpose |
|---|---|---|
| pcb_archive/getHealth | service | gets a period of health records |
| pcb_archive/getJob | service | Attempts to get a job by id |
| pcb_archive/storeJob | service | Attempts to store a job by id |
| pcb_archive/listJob | service | lists all saved jobs envelops |
| pcb_archive/getJobSequence | service | Attempts to get a job sequence by id |
| pcb_archive/storeJobSequence | service | Attempts to store a job sequence by id |
| pcb_archive/listJobSequence | service | List all job sequences by id envelops |
| pcb_archive/getPreparation | service | Attempts to get a IR reference and transform by id |
| pcb_archive/storePreparation | service | Attempts to store a IR reference and transform by id |
| pcb_archive/listPreparation | service | List all preparations by id envelops |
| pcb_archive/getPreparationGroup | service | Attempts to get a preparation group by id |
| pcb_archive/storePreparationGroup | service | Attempts to store a preparation group by id |
| pcb_archive/listPreparationGroup | service | List all preparation groups by id envelops |
| pcb_archive/getIR | service | Attempts to get a intermediate representation by id, gets IR from any stage of creation |
| pcb_archive/storeIR | service | Attempts to store a intermediate representation by id, stores IR from any stage of creation |
| pcb_archive/listIR | service | list all intermediate representation by id envelops |
| pcb_archive/getRaw | service | Attempts to get a raw file by id |
| pcb_archive/storeRaw | service | Attempts to store a raw file by id |
| pcb_archive/listRaw | service | lists all raw file by id envelops |
| pcb_archive/storeCalibration | service | Attempts to store a calibration, fails if the stored calibration is more recent (according to timestamp in the calibration) |
| pcb_archive/getCalibration | service | Attempts to get a calibration by id |
| pcb_archive/listCalibrations | service | Lists all saved calibrations envelops |
| pcb_archive/latestCalibration | service | Gets the most recently saved calibration artifact. |
| pcb_archive/getPattern | service | Attempt to get a pattern by id, May or may not have a calibration id |
| pcb_archive/storePattern | service | Attempt to store a pattern by id, May or may not have a calibration id |
| pcb_archive/listPatterns | service | Lists all saved patterns envelops |
| Parameter | Purpose |
|---|---|
| JobLocation | Where finished jobs are saved. |
| PreparationLocation | location of individual preparations. |
| PreparationGroupLocation | Location of preparation groups. |
| JobSequenceLocation | Location of job sequences. |
| patternLocation | Location of ready to expose patterns. |
| rawLocation | Location of raw uploads before any processing. |
| calibrationLocation | Location of calibrations |
| IRLocation | Location of IR. |
pcb_bridge
This acts as a minimal bridge from ROS to http. Hosting a react website as the tools interface. The bridge is responsible for tracking the browser timeout during test exposures. If more then the time out period has passed (default 20 seconds) the action is cancelled. It is expected that the browser sends a heart beat at a higher frequency (default 5 seconds)
| End point | Type | Purpose |
|---|---|---|
| pcb_bridge/index | Web Page | home page for managing the tool |
| pcb_bridge/prepare | Web Page | Page for uploading, normalizing, and rasterizing art work. Has both dimensional and artwork modes. |
| pcb_bridge/settings | Web Page | page for viewing all saved parameters. |
API
| Resource | Method | Operation |
|---|---|---|
| raw, ir, preparations, preparation-groups, patterns, jobs, sequences, calibrations | GET | Typed archive list; offset/limit pagination |
| raw, ir, preparations, preparation-groups, patterns, jobs, sequences, calibrations | POST | Typed store of `{artifact: ...}` |
| resource/<uuid> | GET | Retrieves typed artifact from the archive |
| normalize/svg, normalize/gbr | POST | Convert raw to IR `{source: uuid, settings_json: "{}"}` |
| render | POST | Preparation to pattern, returns the unsaved pattern artifact. |
| groups/expand | POST | `{group_id, calibration_id, exposure_time}`; generates and saves member preparations, patterns, jobs and sequence. |
| jobs/start, sequences/start | POST | `{job_id}`/`{sequence_id}` to orchestrator action, returns a run_id associated with the action |
| runs/<run_id> | GET | Volatile action acceptance, feed back and terminal result. Uses id given by jobs/start |
| runs/<run_id>/cancel | POST | Request Ros action cancellation |
| health | GET | Archive health history, with after_id/limit pagination |
| status | GET | Latest observed system health, projector boot identity, and projector size in native pixels |
| settings | GET | Arichive - owner storage configuration |
| clear | POST | Emergency clear through `pcb_projector/clear`, does not require session |
| test-exposures | POST | start generation, storage and exposure of a test pattern in one call. Returns a test exposure id. |
| test-exposures/{id}/heartbeat | POST | extend browser authorization |
| test-exposures/{id} | GET | Current exposure state, pattern Id, and terminal result |
| test-exposures/{id}/cancel | POST | Requests to cancel the test exposure |
The test-exposures contract does not require the browser to have boot-id. The projector size for status is queried directly from the projector.
| Parameter | Purpose |
|---|---|
| port | what port to serve at. |
pcb_orchestrator
Handles all internode management and execution of jobs. Also handles running of the health service that monitors ongoing system health.
| End point | Type | Purpose |
|---|---|---|
| pcb_orchestrator/startJob | action | to run a job |
| pcb_orchestrator/startJobSequence | action | run a sequence of jobs |
| pcb_orchestrator/health/freeMemory | topic | How much memory is free |
| pcb_orchestrator/health/job | topic | what current job is being executed |
| pcb_orchestrator/health/snapshot | topic | periodically updates with overall system health. currently tracks memory, cpu, and swap usage using procfs |
| pcb_orchestrator/startTestExposure | action | Takes a test pattern definition (see [Test Patterns]) |
| Parameter | Purpose |
|---|---|
| idleFrequency | When idle how often should health snap shots be taken. |
| exposureFrequency | When exposing how often should health snap shots be taken. |
pcb_renderer
Is responsible for generating all patterns and transforms to images.
| End point | Type | Purpose |
|---|---|---|
| pcb_renderer/svgToIR | service | converts a svg to a normalized IR |
| pcb_renderer/gbrToIR | service | converts a gbr to a normalized IR |
| pcb_renderer/testPatternToIR | service | converts a test pattern into normalized IR, requires pattern name, native width/height, corners, and checkerboard cell size - geometric units are in pixels |
| pcb_renderer/preparationToPattern | service | coverts a preparation (IR + Transform + Calibration) to a pattern, returning the finished pattern for the called to save |
| pcb_renderer/irToPatternNoCalibration | service | converts a normalized IR into a pattern with out using any calibration. This should only be used for test patterns |
| Parameter | Purpose |
|---|---|
| testPatternNmToPx | When generating or parsing the IR format without a calibration, how many nm to one pixel. (default 50) |
pcb_projector
Owns the physical projector. It grants limited time leases to other nodes for when control is needed. A lease is revoked by a emergency clear, end of the lease, or an release.
Each command that requires the changing the projector output must have a valid session, and the current boot Id. The point of the boot id is to prevent a silent failover if the projector node goes down mid exposure, or exposure sequence. The output is a confirmed black before a operation complete is sent.
Timing of an exposure is started from the time a acknowledgement is received from the backend (DRM or simulation). Once that the requested amount of time, or the lease ends the projector will clear its output.
| End point | Type | Purpose |
|---|---|---|
| pcb_projector/session | service | To query status, acquire a session, renew a session, or release a session |
| pcb_projector/present | service | present a pattern, requires a valid session |
| pcb_projector/clear | service | Clears the projector, if emergency is flagged does not require a session |
| pcb_projector/bootId | topic | a unique id generated on boot up |
Convivence packages
pcb_interfaces and pcb_bringup exist for defining all the interfaces and the launch files respectively.
Data formats
All durable artifacts are immutable. Updating an artifact gives it a new ID.
Archive Response Header
The archive to every request will respond with at least:
- Error: null, duplicateId, notFound, or unavailable. Any store request with a duplicate ID irrespective of the payload will have a duplicate ID error
- ID: An optional effected ID (IE when storing what ID it was stored at, or when getting what ID was retrieved in this case should always match request or blank)
Artifact Envelope
Every archive artifact has metadata that contains the following:
- id: UUID
- kind: raw, normalized_ir, preparation, preparation_group, pattern, calibration, job, or job_sequence
- schema_version: integer version of encoding
- name: a human readable name of this artifact. Is not guaranteed to be unique
- created_at: UTC timestamp assigned by the archive
- content_hash: sha-256 of payload
- dependencies: IDs of source artifacts used in creation
- producer: package and version of software that generated it
- supersedes_id: the Id of the artifact this one replaces, can be null.
The archive rejects storing an artifact with a pre-existing id
Raw Source
A raw artifact is the original uploaded bytes stored with it's detected or declared file type. The ID and Hash are assigned by the archive. Raw artifacts are not assumed to be valid
IR and normalization
An IR artifact contains geometry in a canonical coordinate space. A normalized IR is created by converting source artwork with no transforms applied, maintaining its source offset. It contains a payload in the IR format (see below for details) A prepared IR is never saved.
Preparation and preparation group
A preparation refers to exactly one normalized IR and stores the transform to align it in work coordinate space. The transform can include translation, rotation, and scaling.
A preparation group refers to several normalized IRs and one transform that should be applied to each. Applying the transform will move the each normalized IR into work coordinate space. When used a preparation group expands into multiple jobs and patterns.
The unit of all preparations and transforms are integer nanometers and microdegrees. Scaling is unitless, the order of transforms is rotate clockwise about the origin -> translate -> scale from the origin.
Pattern
A pattern the rasterization of a preparation. It's meta data records the source preparation or preparation group ID, renderer version, output width and height in pixels, rasterization settings, and optionally calibration ID.
The pixel convention is:
- One byte per pixel, values 0 and 255
- 255 is fully exposed, 0 is dark
- rows are stored top to bottom, pixels within rows are left to right
- Not row padding, payload length is width * height
Calibration
A calibration artifact stores:
- id: unique revision id
- projectorResolutionPx: [width, height] projector output dimensions in native pixels
- ProjectedWorkingArea: corners in native pixels stored top left, top right, bottom right, bottom left
- PhysicalWorkingArea: width x height in nanometers
Health records
Each health topic message is one health record and is timestamped by the archive using receipt time.
Each health message will contain: the active job id or null if idle, the active job sequence or null if not in active, and memory statistics.
Jobs and Job Sequences
Job envelope
Common job envelope for all jobs and job sequences, this is in addition to the artifact envelope. Jobs and job sequences are immutable. The envelope contains:
- JobType: Exposure, or Sequence
- payload
Exposure job
Is dependent on a calibration and Contains:
- preparation ID
- exposureTime: float in seconds of how long to expose for
- CalibrationId: What calibration was used to generate the pattern, and what the latest should be when it is time to expose.
Job sequence
Contains:
- JobIds: list of job ids in order
IR Format:
{
"ir_version": 1, // version of ir encoded
"stage": normalized | prepared,
"units": "nm",
"converter_metadata: {<Converter settings>},
"shapes" :[ // Each shape is one filled region
{
"id": "shape-1",
"fill_rule": "even_odd",
"operation": expose | clear
"role": "outer", // This is hint and is not binding
"contours":[
{
"start": [x,y] // in nm
"segments": [
{
"type": "line",
"to":[x,y]
},
{
"type": "cubic_bezier",
"control1":[x,y]
"control2":[x,y]
"to":[x,y]
},
],
}
]
},
{
"id": "shape-2",
"fill_rule": "even_odd",
"operation": expose | clear
"role": "hole", // This is hint and is not binding
"contours":[
{
"start": [x,y] // in nm
"segments": [
{
"type": "line",
"to":[x,y],
},
{
"type": "cubic_bezier",
"control1":[x,y],
"control2":[x,y],
"to":[x,y],
},
],
}
]
}
]
}The Rules:
- The role of a shape never changes rendering behavior.
- Each shape cannot be self-intersecting
- Prepared IR is IR that has had a transform applied
- Coordinates are signed 64-bit integers in nanometers.
- Each shape is a closed filled region
- The last point of a contour is always coincident with the start. This applied to each contour, including the end point of beizer segments.
- All Shapes are closed
- A shape with multiple contours with even_odd fill rule will have alternate filled and empty contours, by containment order (preciscly if a ray from inside the contour crosses with a odd number of contours it is filled. If it is even then it is empty)
- Shape operation is expose or clear. Shapes are evaluated in list order, with the last evaluated setting the pixel at that location.
- Empty shapes, invalid contours, and unknown versions are rejected. A converter may approximate a unsupported shape using a supported shapes, if done so the settings used must be recorded in the converter metadata.
- IR source id is carried in the artifact schema
Clear operations are applied across shapes, empty regions are within shapes. In a shape an empty region is unchanged when rendered, a later shape may change it. IE in a clear operation the a empty region is left unchanged, a fill region is set to black. The inverse is true for a fill operation.
Major Change Log
- Removal of the capabilities API.
- Conversion of pcb_renderer to python for better image handling
- Renaming of pcb_calibration to pcb_archive
- renaming of pcb_web to pcb_bridge
- Reduction of scope of pcb_web/pcb_bridge
- Expansion of scope for pcb_archive, pcb_renderer, and pcb_projector.
- Removal of unused ROS topics.
Notes
The choice of integer nanometers as default units is to make rounding explicit, and to have consistent accuracy at all scales in exchange for sacrificing absolute range. In the worst case using Int64 to store data it would give us a maximum size of >500k miles, which is well beyond project requirements.