///|
/// Assembly metadata: purchasing/manufacturing data, fasteners, ports, fits,
/// and bill-of-materials roll-up.
///
/// These records are additive; geometry and kinematics stay in `Component` and
/// `BodyPart`.
///|
/// Purchasing and manufacturing metadata for one part.
pub(all) struct PartMeta {
part_number : String
description : String
supplier : String
supplier_url : String
material : String
process : String
finish : String
unit_cost_usd : Double
notes : String
}
///|
pub fn PartMeta::new(
part_number : String,
description~ : String = "",
supplier~ : String = "",
supplier_url~ : String = "",
material~ : String = "",
process~ : String = "",
finish~ : String = "",
unit_cost_usd~ : Double = 0.0,
notes~ : String = "",
) -> PartMeta {
{
part_number,
description,
supplier,
supplier_url,
material,
process,
finish,
unit_cost_usd,
notes,
}
}
///|
pub fn PartMeta::with_notes(self : PartMeta, notes : String) -> PartMeta {
{ ..self, notes, }
}
///|
pub fn PartMeta::with_supplier_url(
self : PartMeta,
supplier_url : String,
) -> PartMeta {
{ ..self, supplier_url, }
}
///|
/// A per-part purchasing override, typically loaded from an example's
/// `supplier-links.txt`. Empty fields keep the component's existing value.
pub(all) struct SupplierLink {
part_number : String
supplier : String
supplier_url : String
notes : String
unit_cost_usd : Double?
}
///|
pub fn SupplierLink::new(
part_number~ : String,
supplier~ : String = "",
supplier_url~ : String = "",
notes~ : String = "",
unit_cost_usd? : Double,
) -> SupplierLink {
{ part_number, supplier, supplier_url, notes, unit_cost_usd, }
}
///|
fn supplier_link_for(
links : Array[SupplierLink],
part_number : String,
) -> SupplierLink? {
for link in links {
if link.part_number == part_number {
return Some(link)
}
}
None
}
///|
fn with_supplier_link(meta : PartMeta, links : Array[SupplierLink]) -> PartMeta {
match supplier_link_for(links, meta.part_number) {
Some(link) =>
{
..meta,
supplier: if link.supplier == "" {
meta.supplier
} else {
link.supplier
},
supplier_url: if link.supplier_url == "" {
meta.supplier_url
} else {
link.supplier_url
},
notes: if link.notes == "" {
meta.notes
} else {
link.notes
},
unit_cost_usd: match link.unit_cost_usd {
Some(cost) => cost
None => meta.unit_cost_usd
},
}
None => meta
}
}
///|
/// Applies purchasing-link overrides throughout this component tree. Existing
/// values are kept when a link leaves a field empty.
pub fn Component::with_supplier_links(
self : Component,
links : Array[SupplierLink],
) -> Component {
let bodies = self.bodies.map(fn(body) {
match body.part {
Some(meta) => { ..body, part: Some(with_supplier_link(meta, links)), }
None => body
}
})
let fasteners = self.fasteners.map(fn(fastener) {
match fastener.part {
Some(meta) => { ..fastener, part: Some(with_supplier_link(meta, links)), }
None => fastener
}
})
let part = match self.part {
Some(meta) => Some(with_supplier_link(meta, links))
None => None
}
let attachments = self.attachments.map(fn(att) {
{ ..att, child: att.child.with_supplier_links(links), }
})
{ ..self, bodies, fasteners, part, attachments, }
}
///|
/// The kind of hardware a fastener record describes.
pub(all) enum FastenerKind {
Bolt
Screw
Nut
Washer
Insert
}
///|
/// A fastener schedule entry: thread, length, quantity, torque, and the parts
/// or mates it joins.
pub(all) struct Fastener {
name : String
kind : FastenerKind
thread : String
length_mm : Double
/// Thread engagement in the receiving part, mm.
engagement_mm : Double
quantity : Int32
torque_nm : Double
references : Array[String]
part : PartMeta?
}
///|
pub fn Fastener::new(
name : String,
kind : FastenerKind,
thread~ : String = "",
length_mm~ : Double = 0.0,
engagement_mm~ : Double = 0.0,
quantity~ : Int32 = 1,
torque_nm~ : Double = 0.0,
references~ : Array[String] = [],
part~ : PartMeta? = None,
) -> Fastener {
{
name,
kind,
thread,
length_mm,
engagement_mm,
quantity,
torque_nm,
references,
part,
}
}
///|
pub fn Fastener::with_part(self : Fastener, part : PartMeta) -> Fastener {
{ ..self, part: Some(part), }
}
///|
/// A typed interface exposed by a component.
pub(all) enum PortKind {
Mechanical
Power
Signal
Bus
Fluid
Sensor
Ground
}
///|
pub(all) struct Port {
name : String
kind : PortKind
spec : String
}
///|
pub fn Port::new(name : String, kind : PortKind, spec~ : String = "") -> Port {
{ name, kind, spec, }
}
///|
/// A fit record: nominal size plus the allowed range.
pub(all) enum FitClass {
Nominal
Clearance
Transition
Interference
}
///|
pub(all) struct Fit {
name : String
fit_class : FitClass
nominal_mm : Double
min_mm : Double
max_mm : Double
}
///|
pub fn Fit::new(
name : String,
fit_class : FitClass,
nominal_mm~ : Double = 0.0,
min_mm~ : Double = 0.0,
max_mm~ : Double = 0.0,
) -> Fit {
{ name, fit_class, nominal_mm, min_mm, max_mm, }
}
///|
/// One aggregated bill-of-materials line.
pub(all) struct BomLine {
part_number : String
description : String
quantity : Int32
supplier : String
supplier_url : String
material : String
process : String
finish : String
unit_cost_usd : Double
total_cost_usd : Double
notes : String
}
///|
/// A bill of materials: aggregated part lines and a count of bodies without
/// part metadata (explicit placeholders).
pub(all) struct Bom {
lines : Array[BomLine]
mut unassigned : Int32
}
///|
pub fn Bom::new() -> Bom {
{ lines: [], unassigned: 0, }
}
///|
/// Adds `quantity` of `part`, aggregating by part number.
pub fn Bom::add(self : Bom, part : PartMeta, quantity : Int32) -> Unit {
if quantity <= 0 {
return
}
for i in 0.. Unit {
self.unassigned = self.unassigned + quantity
}
///|
pub fn Bom::total_cost_usd(self : Bom) -> Double {
self.lines.fold(init=0.0, fn(acc, line) { acc + line.total_cost_usd })
}
///|
fn csv_field(value : String) -> String {
"\"" + value.replace(old="\"", new="\"\"") + "\""
}
///|
fn csv_row(fields : Array[String]) -> String {
fields.fold(init="", fn(acc, field) {
if acc == "" {
field
} else {
acc + "," + field
}
})
}
///|
/// Renders the bill of materials as CSV with a header and a final newline.
pub fn Bom::to_csv(self : Bom) -> String {
let header : Array[String] = [
"part_number", "description", "quantity", "supplier", "supplier_url", "material",
"process", "finish", "unit_cost_usd", "total_cost_usd", "notes",
]
let rows : Array[String] = [csv_row(header.map(fn(v) { csv_field(v) }))]
for line in self.lines {
rows.push(
csv_row([
csv_field(line.part_number),
csv_field(line.description),
line.quantity.to_string(),
csv_field(line.supplier),
csv_field(line.supplier_url),
csv_field(line.material),
csv_field(line.process),
csv_field(line.finish),
csv_field(line.unit_cost_usd.to_string()),
csv_field(line.total_cost_usd.to_string()),
csv_field(line.notes),
]),
)
}
if self.unassigned > 0 {
rows.push(
csv_row([
csv_field(""),
csv_field("UNASSIGNED"),
self.unassigned.to_string(),
csv_field(""),
csv_field(""),
csv_field(""),
csv_field(""),
csv_field("0.0"),
csv_field("0.0"),
csv_field("bodies or fasteners without PartMeta"),
]),
)
}
rows.fold(init="", fn(acc, row) { acc + row + "\n" })
}
///|
/// Builds the bill of materials for this component tree.
///
/// A component with `part` is treated as a purchased/assembled item: its own
/// bodies are represented by that part, while attachments marked
/// `bom_external` (the default) are still collected. Internal attachments such
/// as a motor's rotor are marked non-external and are not counted separately.
pub fn Component::bom(self : Component) -> Bom {
let bom = Bom::new()
self.collect_bom(bom, false)
bom
}
///|
/// Convenience: the bill of materials as CSV.
pub fn Component::to_bom_csv(self : Component) -> String {
self.bom().to_csv()
}
///|
fn Component::collect_bom(
self : Component,
bom : Bom,
skip_bodies : Bool,
) -> Unit {
let is_part = self.part is Some(_)
// `skip_bodies` means this component is internal to a purchased item (for
// example the rotor or bearings inside a motor). Its own part number and
// fasteners are part of that purchased item, so none of them are counted
// again as separate BOM lines.
if !skip_bodies {
if is_part {
match self.part {
Some(part) => bom.add(part, 1)
None => ()
}
} else {
for body in self.bodies {
match body.part {
Some(part) => bom.add(part, 1)
None => bom.add_unassigned(1)
}
}
}
for fastener in self.fasteners {
match fastener.part {
Some(part) => bom.add(part, fastener.quantity)
None => bom.add_unassigned(fastener.quantity)
}
}
}
for att in self.attachments {
let child_skip = if att.bom_external {
false
} else {
skip_bodies || is_part
}
att.child.collect_bom(bom, child_skip)
}
}
///|
/// Sets purchasing/manufacturing metadata for the whole component.
pub fn Component::with_part(self : Component, part : PartMeta) -> Component {
{ ..self, part: Some(part), }
}
///|
/// Adds a typed interface port.
pub fn Component::add_port(self : Component, port : Port) -> Component {
self.ports.push(port)
self
}
///|
/// Adds a fastener schedule entry.
pub fn Component::add_fastener(
self : Component,
fastener : Fastener,
) -> Component {
self.fasteners.push(fastener)
self
}
///|
/// Adds an explicit fit record.
pub fn Component::add_fit(self : Component, fit : Fit) -> Component {
self.fits.push(fit)
self
}
///|
/// One step in a derived assembly plan: a fastener installation or a child
/// attachment, numbered in the order the tree should be built.
pub(all) struct AssemblyStep {
sequence : Int32
title : String
/// Slash-separated path from the root component.
component : String
/// The joint used to attach this component, when this is an attach step.
joint : String?
/// Fastener schedule entries installed in this step.
fasteners : Array[String]
/// Tools required by those fasteners.
tools : Array[String]
notes : String
}
///|
pub fn AssemblyStep::new(
sequence : Int32,
title : String,
component~ : String,
joint~ : String? = None,
fasteners~ : Array[String] = [],
tools~ : Array[String] = [],
notes~ : String = "",
) -> AssemblyStep {
{ sequence, title, component, joint, fasteners, tools, notes, }
}
///|
/// Renders one step as a single human-readable line.
pub fn AssemblyStep::to_line(self : AssemblyStep) -> String {
let joint = match self.joint {
Some(name) => " (" + name + ")"
None => ""
}
let fasteners = if self.fasteners.length() == 0 {
""
} else {
", fasteners: " + array_join(self.fasteners, ", ")
}
let tools = if self.tools.length() == 0 {
""
} else {
" [" + array_join(self.tools, ", ") + "]"
}
let notes = if self.notes == "" { "" } else { " -- " + self.notes }
self.sequence.to_string() +
". " +
self.title +
" @ " +
leaf_name(self.component) +
joint +
fasteners +
tools +
notes
}
///|
/// The last slash-separated segment of a component path.
fn leaf_name(path : String) -> String {
path.split("/").fold(init="", fn(_, part) { part.to_owned() })
}
///|
fn array_has(items : Array[String], item : String) -> Bool {
items.fold(init=false, fn(acc, value) { acc || value == item })
}
///|
fn array_join(items : Array[String], separator : String) -> String {
items.fold(init="", fn(acc, item) {
if acc == "" {
item
} else {
acc + separator + item
}
})
}
///|
/// Hex-key size for a metric socket-head thread, using the standard sizes.
fn hex_key_for_thread(thread : String) -> String {
match thread {
"M2" => "1.5 mm hex key"
"M2.5" => "2 mm hex key"
"M3" => "2.5 mm hex key"
"M4" => "3 mm hex key"
"M5" => "4 mm hex key"
"M6" => "5 mm hex key"
"M8" => "6 mm hex key"
"M10" => "8 mm hex key"
_ => "hex key"
}
}
///|
fn tool_for_fastener(fastener : Fastener) -> String {
match fastener.kind {
Bolt | Screw => hex_key_for_thread(fastener.thread)
Nut => "wrench"
Washer => "hand tools"
Insert => "soldering iron"
}
}
///|
fn fastener_note(fastener : Fastener) -> String {
let quantity = fastener.quantity.to_string()
let thread = if fastener.thread == "" { "" } else { " " + fastener.thread }
let length = if fastener.length_mm > 0.0 {
" x " + fastener.length_mm.to_string() + " mm"
} else {
""
}
let torque = if fastener.torque_nm > 0.0 {
", " + fastener.torque_nm.to_string() + " N·m"
} else {
""
}
quantity + " x" + thread + length + torque
}
///|
fn Component::collect_component_names(
self : Component,
names : Array[String],
) -> Unit {
names.push(self.name)
for att in self.attachments {
// A fastener that references the joint that installs it is a mounting
// fastener, so it belongs to the attach step rather than this component's
// internal build.
names.push(att.joint_name)
att.child.collect_component_names(names)
}
}
///|
/// A fastener is a mounting fastener when it references another component in
/// the tree; otherwise it is installed while building its own component.
fn fastener_is_mounting(
fastener : Fastener,
self_name : String,
component_names : Array[String],
) -> Bool {
fastener.references.fold(init=false, fn(acc, reference) {
acc || (reference != self_name && array_has(component_names, reference))
})
}
///|
/// Builds the assembly plan by walking the tree depth first.
///
/// A component's own (internal) fasteners are installed first, then each child
/// is built and attached, so children are complete before they are installed.
/// A fastener that references another component in the tree is installed with
/// the attach step that joins those two components.
pub fn Component::assembly_plan(self : Component) -> Array[AssemblyStep] {
let component_names : Array[String] = []
self.collect_component_names(component_names)
let steps : Array[AssemblyStep] = []
self.collect_assembly_steps(self.name, component_names, steps)
steps
}
///|
/// The assembly plan as one numbered line per step.
pub fn Component::assembly_plan_text(self : Component) -> String {
self
.assembly_plan()
.fold(init="", fn(acc, step) { acc + step.to_line() + "\n" })
}
///|
fn Component::collect_assembly_steps(
self : Component,
path : String,
component_names : Array[String],
steps : Array[AssemblyStep],
) -> Unit {
let attach_fasteners : Array[String] = []
for att in self.attachments {
for fastener in self.fasteners {
if fastener.references.fold(init=false, fn(acc, reference) {
acc || reference == att.child.name || reference == att.joint_name
}) {
if !array_has(attach_fasteners, fastener.name) {
attach_fasteners.push(fastener.name)
}
}
}
}
for fastener in self.fasteners {
if !fastener_is_mounting(fastener, self.name, component_names) &&
!array_has(attach_fasteners, fastener.name) {
let tools : Array[String] = [tool_for_fastener(fastener)]
steps.push(
AssemblyStep::new(
steps.length() + 1,
"Install " + fastener.name,
component=path,
fasteners=[fastener.name],
tools~,
notes=fastener_note(fastener),
),
)
}
}
for att in self.attachments {
let child_path = path + "/" + att.child.name
att.child.collect_assembly_steps(child_path, component_names, steps)
let used_fasteners : Array[String] = []
let tools : Array[String] = []
for fastener in att.child.fasteners {
if fastener.references.fold(init=false, fn(acc, reference) {
acc || reference == self.name || reference == att.joint_name
}) {
used_fasteners.push(fastener.name)
let tool = tool_for_fastener(fastener)
if !array_has(tools, tool) {
tools.push(tool)
}
}
}
for fastener in self.fasteners {
if fastener.references.fold(init=false, fn(acc, reference) {
acc || reference == att.child.name || reference == att.joint_name
}) {
if !array_has(used_fasteners, fastener.name) {
used_fasteners.push(fastener.name)
}
let tool = tool_for_fastener(fastener)
if !array_has(tools, tool) {
tools.push(tool)
}
}
}
steps.push(
AssemblyStep::new(
steps.length() + 1,
"Attach " + att.child.name + " to " + self.name,
component=child_path,
joint=Some(att.joint_name),
fasteners=used_fasteners,
tools~,
notes="mate " +
self.name +
"/" +
att.spec.pair.parent +
" -> " +
att.child.name +
"/" +
att.spec.pair.child,
),
)
}
}
///|
/// Checks the hardware data for problems that would make the assembly
/// unbuildable: bad fastener lengths/engagement/torque, missing parts, invalid
/// fits, and duplicate names. Returns one message per problem; an empty array
/// means the data is consistent.
pub fn Component::assembly_checks(self : Component) -> Array[String] {
let warnings : Array[String] = []
self.collect_assembly_checks(self.name, false, warnings)
warnings
}
///|
fn Component::collect_assembly_checks(
self : Component,
path : String,
covered_by_part : Bool,
warnings : Array[String],
) -> Unit {
let self_is_part = match self.part {
Some(_) => true
None => false
}
let self_covered = covered_by_part || self_is_part
let seen_fasteners : Array[String] = []
for fastener in self.fasteners {
if array_has(seen_fasteners, fastener.name) {
warnings.push(path + ": duplicate fastener name '" + fastener.name + "'")
} else {
seen_fasteners.push(fastener.name)
}
if fastener.quantity <= 0 {
warnings.push(
path +
": fastener '" +
fastener.name +
"' has quantity " +
fastener.quantity.to_string(),
)
}
if fastener.length_mm <= 0.0 {
warnings.push(path + ": fastener '" + fastener.name + "' has no length")
}
if fastener.engagement_mm <= 0.0 {
warnings.push(
path + ": fastener '" + fastener.name + "' has no thread engagement",
)
} else if fastener.length_mm > 0.0 &&
fastener.engagement_mm > fastener.length_mm {
warnings.push(
path +
": fastener '" +
fastener.name +
"' engages " +
fastener.engagement_mm.to_string() +
" mm of a " +
fastener.length_mm.to_string() +
" mm screw",
)
}
match fastener.kind {
Bolt | Screw =>
if fastener.torque_nm <= 0.0 {
warnings.push(
path + ": fastener '" + fastener.name + "' has no torque",
)
}
_ => ()
}
if fastener.references.length() == 0 {
warnings.push(
path + ": fastener '" + fastener.name + "' has no references",
)
}
match fastener.part {
None =>
warnings.push(
path + ": fastener '" + fastener.name + "' has no PartMeta",
)
Some(_) => ()
}
}
let seen_ports : Array[String] = []
for port in self.ports {
if array_has(seen_ports, port.name) {
warnings.push(path + ": duplicate port name '" + port.name + "'")
} else {
seen_ports.push(port.name)
}
}
let seen_fits : Array[String] = []
for fit in self.fits {
if array_has(seen_fits, fit.name) {
warnings.push(path + ": duplicate fit name '" + fit.name + "'")
} else {
seen_fits.push(fit.name)
}
if fit.min_mm > fit.max_mm {
warnings.push(path + ": fit '" + fit.name + "' has min > max")
} else if fit.nominal_mm < fit.min_mm || fit.nominal_mm > fit.max_mm {
warnings.push(
path +
": fit '" +
fit.name +
"' nominal " +
fit.nominal_mm.to_string() +
" mm is outside [" +
fit.min_mm.to_string() +
", " +
fit.max_mm.to_string() +
"] mm",
)
}
}
if !self_covered {
for body in self.bodies {
match body.part {
None =>
warnings.push(path + ": body '" + body.name + "' has no PartMeta")
Some(_) => ()
}
}
}
self.collect_electronics_checks(path, warnings)
for att in self.attachments {
// Validate an explicitly paired mate when both connectors resolve. Generic
// default `origin` mates are universal and pass trivially.
match
(
self.mates.get(att.spec.pair.parent),
att.child.mates.get(att.spec.pair.child),
) {
(Some(parent_mate), Some(child_mate)) =>
match
@step_common.MatePair::validate(
att.spec.pair,
parent_mate,
child_mate,
) {
Ok(_) => ()
Err(error) =>
warnings.push(
path +
": joint '" +
att.joint_name +
"' mate '" +
att.spec.pair.parent +
"' -> '" +
att.spec.pair.child +
"': " +
error.message(),
)
}
_ => ()
}
// An internal attachment belongs to this purchased/assembled item; an
// external one is a separate item even when the parent has a part.
let child_covered = if att.bom_external { false } else { self_covered }
att.child.collect_assembly_checks(
path + "/" + att.child.name,
child_covered,
warnings,
)
}
}