1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
|
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Tangible Bit Object System</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="tangible-bit-object-system">
<h1 class="title">Tangible Bit Object System</h1>
<p>The Tangible Bit Object System (TBOS) describes physical objects. It
contains including detailed and automatically processable on how they can
be build, how they can be used, and what they can be used for. The TBOS
takes care of the entire life cycle of an object, including information on
maintenance, part replacement, and repair, and disassembly.</p>
<p>Each object has <em>properties</em> that describe the object. Each object is
associated with <em>processes</em> that describe how the object can be build,
used, maintained, repaired, modified, or dismantled.</p>
<div class="section" id="object-descriptions">
<h2>Object Descriptions</h2>
<p>The most important property of each object are its <em>categories</em> (types).
This allows placing all objects in a type hierarchy. Each category extends
another category, the most general object category is <em>Object</em>; each object
is an instance of one or several category (we allow multiple inheritance
here). The hierarchy of object categories, as known to Tangible Bit, is
stored in <tt class="docutils literal"><span class="pre">doc/object_categories.txt</span></tt> (TODO should be formalized and
moved outside the <tt class="docutils literal"><span class="pre">doc</span></tt> directory; it should be possible to just refer to
categories by ID to remove the dependency on a single authority). The
object category also specified which other properties the object has.</p>
<p>The properties of the <em>Object</em> category, which are shared by all objects,
are as follows:</p>
<pre class="literal-block">
[meta]
prefix: com.tangiblebit.type # prefix used for all IDs in this document
id: object
description: The root of the object hierarchy.
[req] # Required properties
name(freetext): An informal name of the object.
id(string):
An ID uniquely identifying the object; to avoid name clashes, you should
use "reverse domain name notation" (like Java package) starting with a
domain you control. Sample: com.example.coffeemaker if you own the
example.com domain.
summary(freetext): A short (one line) description of what the object is and
what it can be used for.
license(string):
The license under which the object is made available (must be compatible
with CC-SA-BY or a free software/open source license in order to allow
inclusion in the TB object database). On the TBit website there is
controlled vocabulary of license names that should be used in this field
and in the *softwareLicense* field.
[opt] # Optional properties
homepage(string): The homepage of the object.
orderpage(string): A web page where prebuilt copies of the object or kits
or components can be ordered.
producer(string): The company or organization typically (or initially)
producing the object.
description(freetext):
A longer description of the object.
lastModified(timestamp): Timestamp showing when the object metadata or the
files or processes connected with the object where last modified.
weight(mass):
The weight of the object (set to 0 if this is a non-material object).
width(length): The total width of the object, when fitting it into a box (0
if this is a non-material object).
depth(length): The total depth of the object, when fitting it into a box (0
if this is a non-material object).
height(length): The total height of the object, when fitting it into a box
(0 if this is a non-material object).
softwareLicense(string):
The license under which the software related to the object is made
available (must be compatible with CC-SA-BY or a free software/open
source license in order to allow inclusion in the TB object
database). If omitted, the value given in the *license* field is used
instead.
[list] # Properties occurring once or more
category(identifier): List of categories the object belongs to.
maintainer(contact):
List of people to contact regarding questions about the object.
replaces(string):
List of object IDs this object is meant to replace/make obsolete.
[optlist] # Properties occurring any number of times
author(contact):
List of the people which created/packaged the object.
thumbnail(file): List of small visual depictions of the object (pointers to
image files--stored in the *thumbnails* folder).
file(file): List of files associated with the object (pointers to files
stored in the *files* folder).
# Lists of processes associated with the object
build:
List of processes (IDs) explaining how to build/produce the object.
setup:
List of processes (IDs) explaining how to setup the object prior to using
it (comes between build and usage, and can optionally later be repeated
when necessary.) Sample: program channel list on a TV set.
use: List of processes (IDs) explaining how to use the object, in general
or for some specific purpose.
dismantle: List of processes (IDs) explaining how to dismantle/disassemble
the object.
maintain:
List of processes (IDs) explaining how to maintain the object--describes
operations that need to be performed regularly or occasionally to keep
the object in good order. Sample: change oil in a car.
repair: List of processes (IDs) explaining how to repair the object or some
parts of it.
replace: List of processes (IDs) explaining how to replace same part of the
object.
</pre>
<p>TODO include parsed and beautified version of files instead.</p>
<p>Samples of additional properties that could be defined for a VisualDisplay:</p>
<ul class="simple">
<li>resolutionX (int)</li>
<li>resolutionY (int)</li>
<li>displayWidth (length)</li>
<li>displayHeight (length)</li>
</ul>
<p>New object categories can be declared by defining a name and an ID for the
category and by specifying the ID of a parent category (<em>Object</em> or a
category derived from it) and a list of additional properties supported by
the new category. Category declarations are given in the Type Declaration
Language, cf. <tt class="docutils literal"><span class="pre">formats</span></tt>.</p>
<p>The following basic types can be used for additional properties:</p>
<pre class="literal-block">
# The basic types that can be used for atomic fields. Types not defined
# here are complex types, made up of several atomic or complex types.
int: An integer number. External form: as in TDF.
float: A floating point number. External form: as in TDF.
bool: A Boolean value, either "true" or "false".
string: A string. Use this base type for free-form strings that are not
meant to be localized. Strings can contain arbitrary Unicode characters.
External form: as in TDF.
timestamp: A point in time. External form: like the `YAML timestamp
<http://yaml.org/type/timestamp.html>`_ type.
identifier(string):
An identifier, made up of alphanumeric characters and underscores.
freetext(string):
Text that can be localized (translated in other languages).
# Unit types
capacitance(float):
An electric capacitance, measured by default in farad (F).
length(float): A length, measured by default in meter (m).
mass(float): A mass, measured by default in kilogram (kg).
power(float): A (physical) power, measured by default in watt (W).
resistance(float):
A electrical resistance or impedance, measured by default in ohm (Ω).
voltage(float): A voltage (electrical potential difference), measured by
default in volt (V).
# CSV types contain several pieces of information wrapped in a single
# string, formatted as a CSV fragment: items are comma-separated; if an
# item contains commas or newlines, it must be enclosed in quotation marks.
# CSV types are defined by giving a comma-separated list of field names in
# parentheses; each followed by "=" and the field type; a "?" preceding the
# field name marks the field as optional (may be omitted or empty).
contact(?givenName=string, ?surname=string, ?emailAddress=string):
Provides a minimum of contact information about a person: name and
e-mail address.
</pre>
<p>All properties that require a unit come with a "natural unit" taken, when
possible, from the <a class="reference external" href="http://en.wikipedia.org/wiki/International_System_of_Units">International System of Units</a> (meter,
kilogram, second, ampere, degree Celsius, candela, joule, watt, volt,
hertz, ohm, lumen etc.). Thus units need never be stored in the DB. The
obvious exception is money, where a unit (e.g. USD or EUR) must be
supplied.</p>
<p>Additional properties can also be <em>complex types</em>, made up of several
atomic or complex types. Examples of complex types are the <em>file</em> and
<em>process</em> properties of the <em>Object</em> type. Complex types are declared in
the same way as object categories (cf. <tt class="docutils literal"><span class="pre">formats</span></tt>).</p>
</div>
<div class="section" id="process-descriptions">
<h2>Process Descriptions</h2>
<p>Processes describe the life cycle of an object: how it and be built; how it
can be used and what it can be used for; how it can be maintained,
repaired, and modified; and how it can be dismantled and discarded or
recycled when it has reached the end of its life cycle. Without processes,
any object would be pretty useless.</p>
<p>Each process description has the following elements:</p>
<div class="section" id="metadata">
<h3>Metadata</h3>
<pre class="literal-block">
[meta]
prefix: com.tangiblebit.type # prefix used for all IDs in this document
id: process
description: A process description
[req] # Required properties
name(freetext): An informal name and short summary of the process.
id(string):
An ID uniquely identifying the process. Tip: derive from the ID of the
corresponding object (e.g. "com.example.coffeemaker.buildit" for a
process documenting how to build a "com.example.coffeemaker" object).
license(string):
The license under which the process is made available (must be compatible
with CC-SA-BY or a free software/open source license in order to allow
inclusion in the TB process database). On the TBit website there is
controlled vocabulary of license names that should be used in this field
and in the *softwareLicense* field.
[opt] # Optional properties
description(freetext): A description of the process.
homepage(string): The homepage of the process.
lastModified(timestamp):
Timestamp showing when the process description or the files connected
with the process were last modified.
softwareLicense(string):
The license under which the software related to the process is made
available (must be compatible with CC-SA-BY or a free software/open
source license in order to allow inclusion in the TB process database).
If omitted, the value given in the *license* field is used instead.
[list] # Properties occurring once or more
maintainer(contact): List of people to contact regarding questions about
the process (typically same as for the corresponding object).
[optlist] # Properties occurring any number of times
author(contact): List of the people which created/packaged the process
(typically same as for the corresponding object).
replaces(string):
List of process IDs this process is meant to replace/make obsolete.
thumbnail(file): A list of small visual depictions of the process (pointers
to image files--stored in the *thumbnails* folder).
file(file):
List of files that are helpful in order to better understand the process,
but aren't generally necessary in order to execute it (pointers to files
stored in the *files* folder).
</pre>
</div>
<div class="section" id="input">
<h3>Input</h3>
<p>Lists materials and components that are required for the process; including
the amount or the number of instances required. Materials and objects
listed here are used up or transformed during the process.</p>
<p>Input requirements are probably listed using the TB query language, which
might look like this:</p>
<pre class="literal-block">
object ? (category ~ SheetMetal & material = Aluminum & width = 1.5 &
depth = 0.3 height = 0.003 & copies = 12);
material ? (category ~ ABS & amount = 0.5);
</pre>
<p>(12 sheets made from aluminum or steel, size 150x30 cm, height between 3
and 4 mm; and 0.5 kg of ABS plastic.)</p>
<p>A name can be declared before the "?", e.g. <tt class="docutils literal"><span class="pre">material</span> <span class="pre">"MyMaterial"</span> <span class="pre">?</span></tt>.
The name used for referring to the object/material later in scripting,
otherwise the category (e.g. "SheetMetal" or "ABS") is used.</p>
<p>The <a class="reference external" href="http://code.gustavonarea.net/booleano/">Booleano</a>-based query
syntax is straightforward:</p>
<ul class="simple">
<li>Logical operators:<ul>
<li>and: &</li>
<li>or: |</li>
<li>not: !</li>
</ul>
</li>
<li>Comparison operators:<ul>
<li>Equal: = (or maybe ==)</li>
<li>Not equal: !=</li>
<li>Less/greater [or equal] than: < > <= >=</li>
<li>"Similarity": ~ . <tt class="docutils literal"><span class="pre">A</span> <span class="pre">~</span> <span class="pre">B</span></tt> means:<ul>
<li>A is a subcategory of B, if A and B are categories</li>
<li>A contains B as a substring (case-insensitive), if A and B are
strings (similar to SQL LIKE)</li>
<li>Maybe: abs(A-B) < 0.01, if A and B are numbers (rough equality
check)</li>
<li>Undefined (error) otherwise</li>
</ul>
</li>
</ul>
</li>
<li>Items are separated using <tt class="docutils literal"><span class="pre">;</span></tt> or <tt class="docutils literal"><span class="pre">&</span></tt>, indicating that both are
required; or using <tt class="docutils literal"><span class="pre">|</span></tt> indicating that one of the is required.</li>
</ul>
<p>Additional properties, not defined by the object category:</p>
<ul class="simple">
<li>copies (int): the number of instances required, for discrete items.
Default is 1.</li>
<li>amount (mass): the amount (in kilogram) required, for non-discrete items.
No default value. Only one of <em>copies</em> or <em>amount</em> may be specified, but
not both.</li>
</ul>
<p>The input requirements are often called "bill of materials (BOM)", but they
can contain materials <em>and</em> objects.</p>
</div>
<div class="section" id="tools">
<h3>Tools</h3>
<p>Lists tools and resources that are used in the process, but that aren't
used up. Tools are listed in the same way as inputs, e.g.:</p>
<pre class="literal-block">
object ? (category ~ WaterHeater & achievableHeat >= 100
& heatableVolume >= 2);
</pre>
<p>(A water heater than can heat 2 liters of water (or more) to 100 degree
Celsius (or more), required for ca. 15 minutes.)</p>
<p>Additional property:</p>
<ul class="simple">
<li>time (time?): an estimate of the time for which the tool is
required--useful e.g. for cost calculations if a tool is shared or rented
on a temporal basis.</li>
</ul>
</div>
<div class="section" id="constraints">
<h3>Constraints</h3>
<p>Lists conditions that must be true for the process to be performed as
expected. Described in the same way as inputs, e.g.:</p>
<pre class="literal-block">
constraint ? (10 <= EnvironmentTemperature <= 35)
</pre>
<p>(The environmental temperature must be between 10 and 35 °C.)</p>
<p>Implementation note: input, tools, and constraints can be stored as "saved
queries" in the database.</p>
</div>
<div class="section" id="output">
<h3>Output</h3>
<p>The output describes the objects that will be created as a result of the
process, if any. Output is specified in a simple declarative language:</p>
<pre class="literal-block">
object::
category: WaterBoiler
achievableHeat: {60, 80, 90, 100} # a list
heatableVolume: 0..3 # a range
power: 700
weight: 2.8
width: 0.28
depth: 0.2
height: 0.29
</pre>
<p>If an <em>id</em> is specified for the object (recommended), this means that all
the object properties not explicitly defined can be determined by looking
up the object in the database.</p>
<p>(A water boiler that can heat up to 3 liters of water to 60, 80, 90, or 100
°C, needs 700 W, weights 2.8 kg etc.)</p>
<p>For processes that don't <em>create</em> any objects, but only repair, maintain,
or use them, no output will be defined. Processes that dismantle objects
should list the resulting remains or waste as output.</p>
</div>
<div class="section" id="operations">
<h3>Operations</h3>
<p>TODO document new query-like syntax:</p>
<p>Most operations will either be "machine x should run file y" or "the user
shall do as described in file z". And these operations can be ordered or
unordered (order of execution matters, or it doesn't) or there may be
alternatives (if the machine understands Polyps, it should execute this
file, otherwise we have prepared a STL alternative). So my idea is to have
something like the query language we use for defining dependencies in order
to define such operations.</p>
<p>Idea for a basic building block:</p>
<ul class="simple">
<li>toolname: "filename" -- run file <filename> on tool <toolname></li>
</ul>
<p>With about 3 special instructions:</p>
<ul>
<li><p class="first">run: "filename" -- run the file in this computer (e.g. a Python script)</p>
</li>
<li><p class="first">read: "filename" -- the human user should read the file (e.g. a HTML
file) and follow the instructions therein. If two (or more) alternative
versions of the file exist, they should be listed as alternatives:</p>
<pre class="literal-block">
read: (filename.html | filename.txt)
</pre>
<p>Note: recommended documentation format is HTML; alternatives are open
file formats such as plain text, PDF, and ODT (plaintext documentation
can be generated from HTML calling e.g. <tt class="docutils literal"><span class="pre">lynx</span> <span class="pre">-dump</span> <span class="pre">-nolist</span></tt> or
<tt class="docutils literal"><span class="pre">elinks</span> <span class="pre">-no-numbering</span> <span class="pre">-no-references</span></tt>, Markdown or reStructuredText
make it possible to go into the other direction). HTML files shouldn't
contain any scripts; they should be run through <a class="reference external" href="http://tidy.sourceforge.net/">HTML Tidy</a> to ensure well-formedness.</p>
</li>
<li><p class="first">do: "blah blah blah" -- also instructions for the user, but specified
inline as a string instead of a separate file (for short operations)</p>
</li>
</ul>
<p>These blocks can then be combined:</p>
<ul class="simple">
<li>A; B -- execute first A, then B (order matters)</li>
<li>A & B -- execute A and B (order doesn't matter)</li>
<li>A | B -- execute A or B (alternatives). Recommended reading: try the
first which works (if the tool doesn't understand the file format
specified in A, try B instead)</li>
</ul>
<p>TODO largely obsolete:</p>
<p>This is the core of the process description: the list of operations to be
performed as part of the process. Operations are partially ordered: some
must be performed sequentially, others can be performed simultaneously or
in arbitrary order.</p>
<p>For each operation, there is an <em>agent</em> that should realize the
operation--either one of the <em>tools</em> required for the process (or, in some
cases, one of the <em>inputs</em> defined?), or a human.</p>
<p>Operations will ofter refer to one <em>files</em> attached to the process: CNC
router should execute the toolpath defined in file X, human should bolt the
components together as shown in PDF file Y, etc.</p>
<p><em>Variables</em> can be assigned or reassigned by specifying the variable name,
followed by ":=" and an expressions (as in Polyps):</p>
<pre class="literal-block">
varname: 1 + 2;
</pre>
<p>Operations are arranged in <em>blocks</em> (enclosed in curly brackets) that can
be named and/or annotated with a keyword.</p>
<div class="section" id="keyword-blocks">
<h4>Keyword blocks</h4>
<p>Keywords (preceding the opening bracket) either specify the relation
between the operations in the block:</p>
<dl class="docutils">
<dt>sequential</dt>
<dd>Operations must be executed in the defined order--this is the default.</dd>
<dt>parallel</dt>
<dd>Operations can be executed in parallel or in arbitrary order.</dd>
<dt>alternative</dt>
<dd>It's sufficient to execute on of the operations.</dd>
</dl>
<p>Samples:</p>
<pre class="literal-block">
parallel { # execute these operations in any order
doThis();
doThat();
doSomethingElse();
}
sequential { # You can use this inside a parallel block. Otherwise you
# won't need it, as all other blocks are sequential by
# default.
doThis();
doThat();
doSomethingElse();
}
alternative { # select one of those processes
doThis();
doThat();
doSomethingElse();
}
</pre>
<p>Or they specify that the block should be executed zero, once, or possibly
several times depending on the value of an expression; or that it
should be executed for all the items in a list:</p>
<dl class="docutils">
<dt>if <em>expression</em></dt>
<dd>Executes the block if <em>expression</em> evaluates to true; optionally followed
by an <em>elif</em> or <em>else</em> block.</dd>
<dt>elif <em>expression</em></dt>
<dd>Executes the block if <em>expression</em> evaluates to true and if none of the
preceding <em>if</em> and <em>elif</em> blocks was executed; only allowed immediately
after an <em>if</em> and <em>elif</em> block.</dd>
<dt>else</dt>
<dd>Executes the block if none of the preceding <em>if</em> and <em>elif</em> blocks was
executed; only allowed immediately after an <em>if</em> and <em>elif</em> block.</dd>
<dt>while <em>expression</em></dt>
<dd>The block is executed any number of times, as long as <em>expression</em>
evaluates to true.</dd>
<dt>for <em>varname</em> in <em>list</em></dt>
<dd>Executes the block for each of the members in the <em>list</em>, setting
<em>varname</em> to the value of the currently selected list member.</dd>
<dt>for <em>varname</em> in <em>range</em></dt>
<dd>Executes the block for each integer value within the specified range,
setting <em>varname</em> to the current value; both the lower and the upper
limits of the range can be either inclusive or exclusive; both limits of
the range must be integer values. Specifying a number <em>n</em> instead of a
range is identical to specifying the range <em>[0..n[</em> (the loop is executed
<em>n</em> times, indexing starts from 0).</dd>
</dl>
<p>Samples:</p>
<pre class="literal-block">
if *condition* {
doThis();
doThat();
doSomethingElse();
} elif *another-condition* {
doAnotherThing()
} else {
doSomethingStrange()
}
while *condition* {
doThis();
doThat();
doSomethingElse();
}
# The argument of a for loop is a list...
for file in [fileA, fileB, fileC] { # do this for each of the 3 files
doThis();
doThat();
}
# ...or a range...
for i in [1..10] { # repeat 10 times (increasing the value of i)
doThis();
doThat();
}
# ...or a number...
for i in 10 { # repeat 10 times, but this time counting from 0
doThis();
doThat();
}
</pre>
</div>
<div class="section" id="functions-named-blocks">
<h4>Functions (Named Blocks)</h4>
<p>Functions (named blocks) are defined by prepending a function name followed
by a (possibly empty) parameter list before the actual block, separated by
":=". Parameters are comma-separated and enclosed in parentheses.</p>
<p>Functions must be declared at the highest level, they can't be nested within
another block. Function blocks are initially skipped, they must be
explicitly invoked to be executed. Functions can only be invoked after they
have been defined.</p>
<p>Samples for defining and invoking functions:</p>
<pre class="literal-block">
# Defining a function with one parameter
sharpenTheSaw(sharpness) := {
...
}
# Defining a parameterless function:
prepareTools() := parallel {
# function name and keyword can be combined
# (it does not matter in which order the tools are prepared)
sharpenTheSaw(10);
fillWaterInTheHeater();
preheatTheFabber();
}
# Defining a function with multiple parameters
buildLegs(numOfLegs, kindOfWood, diameter) := {
...
}
</pre>
<p>Each process must have exactly one function named <em>main</em>; the process is
run be executing this function. If the process accepts parameters (cf.
below), the <em>main</em> function must accept each of these parameters as
parameter (order doesn't matter, additional parameters are not allowed); if
the process doesn't support parametrization, <em>main</em> must not accept any
parameters.</p>
</div>
<div class="section" id="built-in-functions">
<h4>Built-in Functions</h4>
<p>The following functions are built in:</p>
<p>TODO list: "do", "query", "[object.]run", and "[object.eval]"; return
values can be stored using ":=".</p>
</div>
</div>
<div class="section" id="parameters">
<h3>Parameters</h3>
<p>TODO can be specified as ranges and lists, but how to distinguish from
normal ranges and lists? Use "?=" instead of ":=" ?</p>
<p>It should be possible for a process to accept <em>parameters</em> that influence
the process--for example, if you built a chair, you can configure the exact
length of the legs, specify whether it should have a cushion, select the
color etc.</p>
<p>For each parameter, the supported range or enumeration of values should be
predefined; the user then chooses among the available options.</p>
<p>The choice of parameter values can influence the other elements of the
process--exact input requirements and output specification will depend on
them; some of the operations will change to reflect to them; possibly, the
tools required will change too.</p>
<p>When storing options in the DB, the whole range or enum should be stored in
order to be searchable (e.g. a chair that can be made in any color with
legs between 35 cm and 80 cm should match a search for a red chair with 50
cm legs.) That's more difficult for input/tool requirements, however (we
can calculate and store how much material a 35 cm or a 80 cm chair would
need, but we can't precalculate and store such information for <em>all</em>
possible values). A possible, though imperfect solution would be to store
such information for the <em>minimum</em> and <em>maximum</em> values of numeric
parameters, and for a <em>default</em> value for enum parameters; and to calculate
the exact values on demand.</p>
<p>Example of declaring parameters:</p>
<pre class="literal-block">
# leg length is between 35 cm and 80 cm
leg-length: 0.35..0.80;
# six different colors are available
color: {red, green, blue, yellow, black, white};
</pre>
<p>Example of selecting parameters--syntax is identical to the syntax used for
defining inputs:</p>
<pre class="literal-block">
# we want a blue chair with 50 cm legs
leg-length = 0.5 & color = "blue";
</pre>
<p>TODO calculate output parameters to input parameters and vice versa:
<em>parametrize,</em> optionally <em>invParametrize</em>.</p>
</div>
</div>
<div class="section" id="object-database">
<h2>Object Database</h2>
<p>TODO Describe how objects and processes are stored in the DB.</p>
</div>
<div class="section" id="tangible-bit-object-description">
<h2>Tangible Bit Object Description</h2>
<p>The <em>Tangible Bit Object</em> file format (extension: <em>.tbob</em>) allows
extracting objects with their relevant processes from the database and
sharing them computers and users. A TBOB file can contain one or many
objects with their relevant processes.</p>
<p>A TBOB package is a ZIP file (like formats such as ODT and EPUB).</p>
<p>First-level directories: the file contains one directory for objects and
one for each type of processes it contains:</p>
<pre class="literal-block">
objects
build
setup
use
maintain
repair
replace
</pre>
<p>(Empty directories can be omitted.)</p>
<p>Second-level directories: Each object and each process is stored in a
subdirectory of the corresponding folder, using the object/process ID as
directory name (e.g. <tt class="docutils literal"><span class="pre">objects/com.example.coffeemaker</span></tt>).</p>
<p>Each object is represented by three simple text files, written in the
Tangible Bit Declaration Language:</p>
<ul class="simple">
<li>properties.tdl: contains the object properties</li>
<li>processes.tdl: index of processes associated with the object</li>
<li>files.tdl: index of files associated with the object</li>
</ul>
<p>-> TODO Or probably just a single file <tt class="docutils literal"><span class="pre">object.tb</span></tt> defining the object
properties (without any sections).</p>
<p>Each process is represented by five simple text files:</p>
<ul class="simple">
<li>properties.tdl: contains the process metadata</li>
<li>dependencies.tql: lists the input, tools, and constraints required
(written in Tangible Bit Query Language)</li>
<li>result.tdl: defines the output and the allowed parameter settings</li>
<li>operations.top: defines the list of operations to be performed (written
in Tangible Bit Operations Language)</li>
<li>files.tdl: index of files associated with the process</li>
</ul>
<p>-> TODO Or probably just a single file <tt class="docutils literal"><span class="pre">process.tb</span></tt> with up to 7
sections:</p>
<ul class="simple">
<li>[properties]: defines the process properties</li>
<li>[constraints]: the constraints that must be fulfilled in order to run the
process (optional)</li>
<li>[tools]: the required tools (optional)</li>
<li>[input]: the required input (optional)</li>
<li>[output]: the output of the process (optional)</li>
<li>[operations]: list of operations (instructions to be followed by a human
or a machine) (optional)</li>
<li>[files]: other files associated with the process (optional)</li>
</ul>
<p>TODO explain "dirball" concept for instructions (e.g. HTML ball).</p>
<p>If an object or process contains files, they are stored in a third-level
folder named <tt class="docutils literal"><span class="pre">files</span></tt>.</p>
<p>TODO mimetype file?; internationalization/translated strings?</p>
<p>Sample directory structure:</p>
<pre class="literal-block">
objects/
com.example.coffeemaker/
properties.tdl
processes.tdl
files.tdl
files/
thumbnail.gif
frontview.jpg
build/
com.example.coffeemaker.buildit/
properties.tdl
dependencies.tql
result.tdl
operations.top
files.tdl
files/
blueprint.iges
</pre>
<p>TODO Ensure that it's OK to package GPL'ed software with non-GPL'ed content
in a single ZIP file (should be).</p>
</div>
<div class="section" id="to-do">
<h2>To Do</h2>
<ul class="simple">
<li>Decide on syntax to use in <em>formattedtext</em> (Markdown or WikiCreole?).</li>
<li>Write sample object package (Drawdio?) and tutorial/overview document on
documenting and packing objects.</li>
<li>Get in dialog with people creating and using free designs about what they
need and whether our approach suits them.</li>
<li>Document format of declarations (DecL language) and write parser; define
literal form / parse expression of the <em>basetypes</em>.</li>
<li>Write database generator that reads the type declarations and creates or
updates the database scheme accordingly.</li>
<li>Define and publish controlled vocabulary of recommended license names and
of the roles of files.</li>
<li>See TODOs above.</li>
</ul>
</div>
</div>
</body>
</html>
|
