DE

Solo developer

Dull Edge Technologies

Documentation

Software Specification V0.6

Home

A document for Software Specification V0.6.

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:

Image pipe line.drawio.svg

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 pointTypePurpose
pcb_archive/getHealthservicegets a period of health records
pcb_archive/getJobserviceAttempts to get a job by id
pcb_archive/storeJobserviceAttempts to store a job by id
pcb_archive/listJobservicelists all saved jobs envelops
pcb_archive/getJobSequenceserviceAttempts to get a job sequence by id
pcb_archive/storeJobSequenceserviceAttempts to store a job sequence by id
pcb_archive/listJobSequenceserviceList all job sequences by id envelops
pcb_archive/getPreparationserviceAttempts to get a IR reference and transform by id
pcb_archive/storePreparationserviceAttempts to store a IR reference and transform by id
pcb_archive/listPreparationserviceList all preparations by id envelops
pcb_archive/getPreparationGroupserviceAttempts to get a preparation group by id
pcb_archive/storePreparationGroupserviceAttempts to store a preparation group by id
pcb_archive/listPreparationGroupserviceList all preparation groups by id envelops
pcb_archive/getIRserviceAttempts to get a intermediate representation by id, gets IR from any stage of creation
pcb_archive/storeIRserviceAttempts to store a intermediate representation by id, stores IR from any stage of creation
pcb_archive/listIRservicelist all intermediate representation by id envelops
pcb_archive/getRawserviceAttempts to get a raw file by id
pcb_archive/storeRawserviceAttempts to store a raw file by id
pcb_archive/listRawservicelists all raw file by id envelops
pcb_archive/storeCalibrationserviceAttempts to store a calibration, fails if the stored calibration is more recent (according to timestamp in the calibration)
pcb_archive/getCalibrationserviceAttempts to get a calibration by id
pcb_archive/listCalibrationsserviceLists all saved calibrations envelops
pcb_archive/latestCalibrationserviceGets the most recently saved calibration artifact.
pcb_archive/getPatternserviceAttempt to get a pattern by id, May or may not have a calibration id
pcb_archive/storePatternserviceAttempt to store a pattern by id, May or may not have a calibration id
pcb_archive/listPatternsserviceLists all saved patterns envelops
ParameterPurpose
JobLocationWhere finished jobs are saved.
PreparationLocationlocation of individual preparations.
PreparationGroupLocationLocation of preparation groups.
JobSequenceLocationLocation of job sequences.
patternLocationLocation of ready to expose patterns.
rawLocationLocation of raw uploads before any processing.
calibrationLocationLocation of calibrations
IRLocationLocation 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 pointTypePurpose
pcb_bridge/indexWeb Pagehome page for managing the tool
pcb_bridge/prepareWeb PagePage for uploading, normalizing, and rasterizing art work. Has both dimensional and artwork modes.
pcb_bridge/settingsWeb Pagepage for viewing all saved parameters.

API

ResourceMethodOperation
raw, ir, preparations, preparation-groups, patterns, jobs, sequences, calibrationsGETTyped archive list; offset/limit pagination
raw, ir, preparations, preparation-groups, patterns, jobs, sequences, calibrationsPOSTTyped store of `{artifact: ...}`
resource/<uuid>GETRetrieves typed artifact from the archive
normalize/svg, normalize/gbrPOSTConvert raw to IR `{source: uuid, settings_json: "{}"}`
renderPOSTPreparation to pattern, returns the unsaved pattern artifact.
groups/expandPOST`{group_id, calibration_id, exposure_time}`; generates and saves member preparations, patterns, jobs and sequence.
jobs/start, sequences/startPOST`{job_id}`/`{sequence_id}` to orchestrator action, returns a run_id associated with the action
runs/<run_id>GETVolatile action acceptance, feed back and terminal result. Uses id given by jobs/start
runs/<run_id>/cancelPOSTRequest Ros action cancellation
healthGETArchive health history, with after_id/limit pagination
statusGETLatest observed system health, projector boot identity, and projector size in native pixels
settingsGETArichive - owner storage configuration
clearPOSTEmergency clear through `pcb_projector/clear`, does not require session
test-exposuresPOSTstart generation, storage and exposure of a test pattern in one call. Returns a test exposure id.
test-exposures/{id}/heartbeatPOSTextend browser authorization
test-exposures/{id}GETCurrent exposure state, pattern Id, and terminal result
test-exposures/{id}/cancelPOSTRequests 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.

ParameterPurpose
portwhat 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 pointTypePurpose
pcb_orchestrator/startJobactionto run a job
pcb_orchestrator/startJobSequenceactionrun a sequence of jobs
pcb_orchestrator/health/freeMemorytopicHow much memory is free
pcb_orchestrator/health/jobtopicwhat current job is being executed
pcb_orchestrator/health/snapshottopicperiodically updates with overall system health. currently tracks memory, cpu, and swap usage using procfs
pcb_orchestrator/startTestExposureactionTakes a test pattern definition (see [Test Patterns])
ParameterPurpose
idleFrequencyWhen idle how often should health snap shots be taken.
exposureFrequencyWhen exposing how often should health snap shots be taken.

pcb_renderer

Is responsible for generating all patterns and transforms to images.

End pointTypePurpose
pcb_renderer/svgToIRserviceconverts a svg to a normalized IR
pcb_renderer/gbrToIRserviceconverts a gbr to a normalized IR
pcb_renderer/testPatternToIRserviceconverts a test pattern into normalized IR, requires pattern name, native width/height, corners, and checkerboard cell size - geometric units are in pixels
pcb_renderer/preparationToPatternservicecoverts a preparation (IR + Transform + Calibration) to a pattern, returning the finished pattern for the called to save
pcb_renderer/irToPatternNoCalibrationserviceconverts a normalized IR into a pattern with out using any calibration. This should only be used for test patterns
ParameterPurpose
testPatternNmToPxWhen 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 pointTypePurpose
pcb_projector/sessionserviceTo query status, acquire a session, renew a session, or release a session
pcb_projector/presentservicepresent a pattern, requires a valid session
pcb_projector/clearserviceClears the projector, if emergency is flagged does not require a session
pcb_projector/bootIdtopica 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:

Schema-like-Pseudocode
{
  "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.