Users Guide

A full project sync, clear, and build cycle is shown in this sequence diagram. The actions shown in the diagram are described in more detail in the section below.

@startuml participant "Vendor" as vendor actor "User" as user participant "Django CTB" as ctb participant "Git Server" as git user -> ctb: Ensure inventory exists user -> git: Create new repository user -> git: Commit BOM user -> ctb: Create new project user -> ctb: Create new project version loop Until project syncs user -> ctb: Sync project version (action!) activate ctb ctb -> git: Get BOM activate git git --> ctb: BOM deactivate git ctb -> ctb: Parse BOM loop For each BOM row alt Part represented by BOM row exists ctb -> ctb: Create project part from BOM row else ctb -> ctb: Create missing parts refs end end alt No missing part refs created ctb -> ctb: Mark project version as "synced" end deactivate ctb alt Project version not "synced" loop Until all missing part refs are addressed alt Part specification is correct in BOM user -> ctb: Create part for missing part ref else A substitute part exists which will statisfy the design user -> ctb: Update missing project part with a substitute part (and remove "Missing part description") else user -> user: Update BOM user -> git: Commit BOM end end end end user -> ctb: Create new project build referencing project version loop Until project build clears user -> ctb: Update project parts to reflect "optional" status or make part substitutions user -> ctb: Clear project build (action!) activate ctb loop For each project part associated with project version alt Sufficient inventory of part to complete build ctb -> ctb: Create reservation for part ctb -> ctb: Deduct reservation quantity from inventory line else ctb -> ctb: Create build part shortage for part end end alt No build part shortages created for project build ctb -> ctb: Mark project build as "cleared" end deactivate ctb alt Project build not "cleared", will use fallback parts which satsify design loop For each project build part with appropriate fallback part user -> ctb: Define fallback part for shortage end else Project build not "cleared", will place orders user -> ctb: Create vendor orders from shortages (action!) activate ctb loop For each project build part to order alt Vendor part exists to match part ctb -> ctb: Ensure order to vendor exists ctb -> ctb: Ensure order line for part exists ctb -> ctb: Increase order amount by shortage quantity end end deactivate ctb user -> ctb: Add lines and update quantities in vendor orders loop [async] For each vendor order user -> vendor: Place order activate vendor vendor -> vendor: Reticulate splines vendor --> user: Ship order deactivate vendor user -> ctb: Fulfill vendor order (action!) activate ctb loop For each vendor order line ctb -> ctb: Credit inventory line end ctb -> ctb: Mark vendor order as "fulfilled" deactivate ctb end end end alt Nominal situation user -> user: Build project (sweet action) user -> ctb: Complete project build (action!) activate ctb loop For each project build reservation ctb -> ctb: Mark reservation as "utilized" end ctb -> ctb: Mark project build as "complete" deactivate ctb else Decided not to build user -> ctb: Cancel project build (action!) activate ctb loop For each project build reservation ctb -> ctb: Credit inventory line with reservation quantity ctb -> ctb: Delete reservation end ctb -> ctb: Remove status from project build deactivate ctb end @enduml

Actions

The behaviors of this package are manifest as a set of actions which can be performed on certain objects. Each of these actions is avialable as a Django Admin action run in a dramatiq worker as a background task. The service methods are available as well to allow integration of this package into your ecosystem.

Each action is described below.

Complete Order

  • For each VendorOrderLine in the current vendor order:

    • Creates an InventoryLineAction,

    • Adds the ordered quantity of parts to the InventoryLine associated with the Part in the vendor order.

  • Persiss the fulfilled time for the vendor order

Sync Project Version

  • Reads the current project version bill of materials (BOM) from the git repo and commit associated to the Project and ProjectVersion.

  • Creates a ProjectPart and ProjectPartFootprintRef for each line on the BOM.

    • If there is are any ImplicitProjectParts associated to the Package for a Part then a ProjectPart will be created for the implicit part.

    • If a BOM line cannot be matched to any part then:

      • If the BOM line has “Vendor” equal to “Mouser” and the CTB_MOUSER_API_KEY is set then a Part will be created to match the resource in the Mouser Search API wich matches the “PartNum” from the BOM line,

      • Else a ProjectPart will be created with a missing_part_desription rather than a part relation. This dissonance must be resolved manually by correcting the BOM or by creating a suitable Part and re-syncing the project version.

  • Removes any outdated ProjectPart.

  • Persists the sync time for the project version.

Clear to Build

  • Looks for sufficient quantity to cover the bills of material for the project build lot in inventories with common owner to project build.

  • If sufficient quantity is found then those parts necessary are reserved from their inventory lines, and the ProjectBuild cleared time is persisted.

  • Otherwise, a ProjectBuildPartShortage is created for each part that is short indicating lacking quantity.

Cancel Build

  • Releases any ProjectBuildPartReservation associated with the project build, returning that number of parts to their respective inventory lines.

Complete Build

  • Utilizes any ProjectBuildPartReservation associated with the project build, forever removing that number of parts from their respective inventory lines.

Generate Orders from Shortfalls

  • Searches for all ProjectBuildPartShortage objects associated with a selected ProjectBuild.

  • Creates VendorOrder and VendorOrderLine objects to cover shortages for any Part which has a VendorPart

  • Will reuse existing VendorOrder and VendorOrderLine objects—adding to the order quantity—if they exist for a Part.

Models

Django Clear-To-Build utilizes the following data model to achieve those actions and persist the data required to perform those actions.

The relationships between the data are depicted in this handy diagram:

The Django models themselves are described below:

Vendor

Places where parts can be procured. e.g. Mouser, Tayda Electronics

Part

Individual parts which are available for procurement from a vendor and will be assembled into a project. e.g. a 100 Ohm surface mount (0805) resistor, or an NPN TO-92 transistor.

The value attribute of the part will be matched to the value row on the bill of materials.

Package

The form factor for a part. E.g. Surface mount 0805, or TO-92.

Footprint

The manifestation of the part onto the printed circuit board. The footprint appears on the bill of materials, parts will be selected based in part on the footprint name match.

VendorPart

The representation of a part as sold by a vendor. Pricing, item numbers, url paths are stored here.

Owner

The entity who owns the physical inventory and projects. This optionally maps to a User. All the models described below this section are traceable (explicitly or indirectly) to an owner allowing this entity sole access to those resources. Any models documented above this section are shared among all users (although CRUD permissions may still be exercised).

VendorOrder & VendorOrderLine

Individual orders (and the line items of the order) of parts from a vendor. When orders are fulfilled the parts in the order will be represented as inventory lines.

VendorOrder objects are explicitly tied to an owner.

InventoryLine

A collection of parts on hand as represented by individual lines. Inventory lines reference a specific part (independent of vendor_part) and provide the quantity of unreserved parts on hand.

InventoryLine objects are explicitly tied to an owner.

InventoryAction

Tracks changes to inventory lines when orders are fulfilled and when project build parts are reserved

Project

A thing you are building. This is a thin model with just a name and a url to a git repo. The repo must have a CSV file which is the Bill Of Materials (BOM) for the project. KiCAD generates such BOMs as a default feature.

Project objects are explicitly tied to an owner.

ProjectVersion

A point-in-time representation of the project. Requires a commit ref (branch, tag, or commit hash) which exists in the repository, and the path within the repo to the bill of materials.

It is recommened that you set the commit_ref to the default branch for the repo until your bill of materials has stabilized, after this point a git tag is a useful placeholder for the state of a repository at a specific project version. (The author uses tags like v0, v1, etc. once manufacturing of a project version has begun.)

ProjectPart & ProjectPartFootprintRef

Upon sync (described below), the parts represented on the bill of materials will be associated to the project. Each footprint ref (e.g. R12 and C3) that appears in the bill of materials will be represented.

ProjectPart may be marked as “optional” (via the is_optional attribute), indicating that they may be excluded from a ProjectBuild. ProjectPart may have a substitute_part which, when provided, will completely replace the part in the clear-to-buld process (adding a substitute_part to an already cleared project will have no effect, you will have to trigger the project to be cleared again).

ImplicitProjectPart

Sometimes there are parts which don’t appear on the bill of materials but that will be included in the final project. An example is the knobs are added to the potentiometer, and the bezels for the LEDs. They’re not electrical components, but they are needed for a complete build.

Parts like these can be associated to a given Package and will be included in as a ProjectPart when the bill of materials sync process for a project version is complete.

ImplicitProjectPart objects are explicitly tied to an owner.

ProjectBuild

Represents a manufacturing run of a project version. Specify the number of instances of the project version that you will build.

Any ProjectPart objects which were marked “optional” may be added to the excluded_project_parts. When added, these project parts will not be omitted from clearing actvities.

When cleared (described below), the parts needed to build the lot will be reserved from the inventory. When completed these reservations will be utilized.

VendorOrder objects and lines therein can be created for any ProjectBuild object which has shortfalls by selecting the project build from the admin index and running the “Generate orders from shortfalls” action.

ProjectBuildPartShortage

When a project build cannot be cleared due to a lack of parts in the inventory a part shortage will be created.

A fallback_part can be defined for any part shortage, the part specified will be used to fill that shortage the next time the build is cleared.

ProjectBuildPartReservation

When a project build is cleared reservations for each part will be created. If the build is canceled then the reservations will be disolved and the parts will be returned to the inventory.

When the build is complete the reservations are marked utilized.