Find file
73d78d6 Apr 9, 2013
103 lines (51 sloc) 4.61 KB

Contributing to ChipDB

You can contribute to ChipDB by updating/enhancing existing data, or by adding new parts definitions. Parts are specified using YAML. (I chose YAML back in the day because it's more human-writable than JSON, and I typed in a lot of these things by hand.)

File naming

One YAML file should represent one part, or a family of parts that all share a common pinout and roughly similar specifications. By convention, file names contain only uppercase letters, numbers, and hyphens -. If the properly-formatted part name contains lowercase letters or other characters (examples: ATmega328P, uPD7720), it can be specified with a name property (see below).

File contents should consist of 7-bit ASCII characters only. All special characters should be escaped with HTML entities.

Definition syntax

At the root of the file should be a dictionary with the following fields:


Optional. Use if the properly-formatted part name is different from the filename. For example, ATMEGA168.yaml defines name: ATmega168 because filenames should only include uppercase letters.


Required. A one-line description of the part, such as: "8-bit shift register with 3-state output register".


Required. This field was intended to indicate how the pin diagram of this part should be drawn. The only value used in the original database was DIP.


Required. The total number of pins.


Optional. If the part belongs to a large family, like the 7400 or 4000 series, it can be specified with this parameter. It is currently unused by ChipDB but could be used by other frontends to group parts by family. Currently defined families include 7400, 4000, linear, and Atmel.


Required. The URL of an up-to-date version of the manufacturer's datasheet.


Optional. If similar parts share this pinout, you can specify an array of their names. For example, ATMEGA168.yaml defines aliases: [ATmega48, ATmega88, ATmega328P]. This must be an array, even if there is only one alias.


Required. An array of pin definitions. The number of elements must match the indicated pincount. See the section "Pin definitions."


Optional. An array of spec definitions. See the section "Spec definitions".


Optional. An array of additional explanatory notes.

Pin definitions

Each pin definition is a dictionary with three fields:


Required. The pin number. I suppose this is redundant, but it could theoretically be used to specify a non-numeric pin number. (lol)


Required. The pin symbol. Typically all-uppercase. In the case of a single-supply part, the supply pin should be Vcc and the ground pin should be GND. Unused pins should be written as NC for "no connection." May contain spaces, and subscript/overbar characters. See "Subscripts and overbars."


Required. Short description of the pin function. By convention, the first word is not capitalized. May contain subscript/overbar characters.

Spec definitions

The specs array can be used to define a small table of basic specifications. Each definition is a dictionary with the following fields:


Required. Parameter name, such as "Supply voltage" or "Slew rate".


Required. Parameter value. An array can be used to specify multiple values, like a minimum and maximum, e.g. [8 (min), 36 (max)]


Optional. Parameter unit, like V or mA. Non-ASCII units should be written with HTML entities; e.g. Ω instead of Ω.

Subscripts and overbars

ChipDB recognizes special syntax for overbars and subscripts in pin definitions, spec definitions, and notes.


If a sequence of non-whitespace characters is preceded by two underscores, it will be displayed as a subscript. Example: D__0 becomes D0, V__REF becomes VREF.


Tildes can be used to add overbars to characters. If a sequence of non-whitespace characters is preceded by a tilde, a line will be drawn above them. Example: ~OE becomes OE.

To add an overbar to a portion of a word, surround it with tildes. Example: ~RESET~/SYNC becomes RESET/SYNC, and ~CP~__0 becomes CP0

To include a literal tilde in the definition, use the HTML entity ~. If for some bizarre reason you want two or more literal underscores next to each other, use the HTML entity for underscore: _.