From 3589b580d5b9d26b3c4257bf51c09f9773fd8d60 Mon Sep 17 00:00:00 2001 From: RogueM Date: Tue, 29 Dec 2015 17:34:46 +0100 Subject: [PATCH] overlay template and revised ReadMe --- src/README.md | 36 ++++++------------------------- src/de/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/en/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/es/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/fr/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/it/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/pt/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ src/tr/template/overlay.md | 44 ++++++++++++++++++++++++++++++++++++++ 8 files changed, 315 insertions(+), 29 deletions(-) create mode 100644 src/de/template/overlay.md create mode 100644 src/en/template/overlay.md create mode 100644 src/es/template/overlay.md create mode 100644 src/fr/template/overlay.md create mode 100644 src/it/template/overlay.md create mode 100644 src/pt/template/overlay.md create mode 100644 src/tr/template/overlay.md diff --git a/src/README.md b/src/README.md index ab5f112..67b6e54 100644 --- a/src/README.md +++ b/src/README.md @@ -1,41 +1,19 @@ #Pinout Overlays A Pinout overlay describes the functions of the Raspberry Pi pins for a specific board. +An overlay is specified by a Markdown file containing mandatory and optional fields as well as an extended long-description. -An overlay is constructed from a JSON file and, optionally, a markdown file containing an extended long-description. +The Markdown overlay file must include as a minimum a "name", "manufacturer", (short) "description", main "url", and last but not least a "pin" array defining all the pins that the board uses. It is also recommended to specify the header "pincount" and board "formfactor", as well as whether the board includes an "eeprom" (for us to ensure the HAT specifications are respected where appropriate). -##JSON Format +A long description is also highly desirable so that visitors to the site can get an introduction to the add-on boards featured on the site if they are not familar with them. -The JSON overlay file must include a name, manufacturer name, URL, description and a "pin" array defining all the -pins that the board uses. +Note that the pin array must list each pin by its *physical* location, and include at least a "name" describing the function of that pin. -If a counterpart .md file is present in description/overlay it will be used for the long description. - -The pin array must list each pin by its *physical* location, and include at least a "name" describing the function -of that pin. - -Optionally each pin definition can include a "mode" flag, which defines the pin as an "input" or an "output". - -A pin can also have an "active" value, which defines it as "high" or active "low". +Optionally each pin definition can include a "mode" flag, which defines the pin as an "input" or an "output". A pin can also have an "active" value, which defines it as active "high" or active "low". I2C and SPI pins should be included if your board uses them, however they will generally be intepreted as being shared and usable with muliple boards unless you explicitly define them as being an "input" or "output". -Example: +Power pins and EEPROM should specifically be excluded, but specifying the "power" and "eeprom" fields are highly recommended if that info is known (please check the board schematic, this info is typically not difficult to find!) -```json -{ - "name": "Explorer HAT", - "manufacturer": "Pimoroni", - "url": "https://github.com/pimoroni/pibrella", - "description": "An all-in-one light, input and output add-on board.", - "pin": { - "7": { - "name": "Green LED" - }, - "11": { - "name": "Yellow LED" - } - } -} -``` +See the overlay template.md for more information. We recommend you use this template as a starting point for any new add-on board submission. \ No newline at end of file diff --git a/src/de/template/overlay.md b/src/de/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/de/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/en/template/overlay.md b/src/en/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/en/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/es/template/overlay.md b/src/es/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/es/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/fr/template/overlay.md b/src/fr/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/fr/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/it/template/overlay.md b/src/it/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/it/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/pt/template/overlay.md b/src/pt/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/pt/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased diff --git a/src/tr/template/overlay.md b/src/tr/template/overlay.md new file mode 100644 index 0000000..8a15d7e --- /dev/null +++ b/src/tr/template/overlay.md @@ -0,0 +1,44 @@ + +#my add-on board + +Use this section to provide additional information such as fonctionality, technical parts, install requirements, etc +The overlay itself uses the following fields, some of which are mandatory, as noted below: + +MANDATORY +name: the board name as it will appear in the board selection menu at pinout.xyz +manufacturer: the manufacturer's name +description: a short description of what the add-on board provides +url: the main URL for the product providing detailed technical information about the board +pin: an array of the pins used. Do not specify power or EEPROM pins as part of the array! + +DESIRABLE +formfactor: the board's form factor. Valid values currently are Custom, HAT and pHAT. +pincount: the header pin count, typically 26 or 40 but shims/custom boards are acceptable. +eeprom: whether the board includes an eeprom (required by 'HAT' specs!) +power: the supply logic required by the board. Valid values are 3v3, 5v and 3v3,5v. +i2c: if the board uses i2c, a list of the bus address(es) and device(s) identification + +OPTIONAL +github: github repository address +buy: URL where the board can be purchased