HTTP_200_OK
{
"categories": "",
"parts": ""
}HTTP libraries are a type of KiCad symbol library that sources data about parts for an external source such an ERP system. They do not contain any symbol or footprint definitions as standard KiCad libraries do. Instead, they reference to symbols and footprints found in other KiCad libraries.
HTTP libraries are read only for now but will eventually support read/write in the future. At the moment only REST or REST-Like APIs are supported but support for other libraries could be added easily.
Authentication is done via an Access Token only; usually issued by the providing application. The token will be used in every request using the following header: 'AUTHORIZATION': 'Token usertokendatastring'.
Different to ODBC, the REST API provides the information already pre-formatted. KiCad does not know anything about tables, nor does it need to know anything about the underlying database structure of the providing application (API).
KiCad expects a root-URL to access the library. This must be provided via the Configuration File. There are two endpoints which will provide all data necessary to KiCad. Those are called:
categories
parts
Return all parts belonging to a category with ID = 16 using the root-url as shown in the config file: {root-url}/parts/category/16.json
Another example would be using a non integer ID such as Resistors {root-url}/parts/category/Resistors.json:
As shown further below, KiCad expects an ID (numeric or not) which is used to query the API and an optional human-readable name which is displayed as part name to the user. If the API does not return the optional nameid
Please note that KiCad expects strings only. All integers, Boolean values, doubles, floats etc must be converted to strings when responding to requests.
KiCad queries the root-URL and expects it to return a dictionary with the endpoints as key-value pairs.
HTTP_200_OK
{
"categories": "",
"parts": ""
}Note: Only keys are validated. The values can be left blank or set to the actual URL.
To fetch the categories, KiCad queries {root-url}/categories.json using a standard GET request. KiCad expects the server to respond with a JSON formatted array holding one or more categories. It expects only an id and a name for each category and will display those as libraries inside the Symbol Chooser. Part belonging to this category will be displayed underneath those respectively.
HTTP_200_OK
[
{
"id": "16",
"name": "Active Parts/Clock and Timer ICs",
},
{
"id": "17",
"name": "Active Parts/Driver ICs",
},
{
"id": "20",
"name": "Active Parts/Embedded Processors and Controllers",
},
{
"id": "22",
"name": "Active Parts/Interfaces",
},
{
"id": "15",
"name": "Active Parts/Logic ICs",
}
]To display parts underneath a certain category inside KiCad’s Symbol Chooser, KiCad queries the parts endpoint using a standard GET request: {root-url}/parts/category/16.json; with 16 being a numerical example ID for a specific category. As server response, KiCad expects an array containing one or more parts for that specific category.
For each part KiCad expects only an ididnamedescription
HTTP_200_OK
[
{
"id": "69",
"name": "830050789",
"description": "CRYSTAL 32.7680KHZ 12.5PF SMD"
},
{
"id": "40",
"name": "NE555PSR",
"description": "IC OSC SINGLE TIMER 100KHZ 8SO"
},
{
"id": "238",
"name": "TLC555CPSR",
"description": "IC OSC SINGLE TIMER 2.1MHZ 8SO"
}
]TIP: Since the part details are just for the high-level overview within the Symbol Chooser, one should only respond with the minimum data needed. This will speed up the data acquiring process and consequently enhance the user experience. Therefore, KiCad expects only the minimum amount of detail needed (see example above) to display the parts inside the Symbol Chooser. Any other key/value pairs are ignored at this stage. However, the API can send the full details if that’s easier to implement and bandwidth is not a concern.
When a user clicks on a part inside the Symbol Chooser, KiCad will try to retrieve full detailed information about the part using the parts endpoint and a standard GET request: {root-url}/parts/16.json. KiCad expects a single JSON object with the following keys as shown below (Note: the name
The dict fields
Each KiCad FIELD is represented using a dict, and must contain at least the the valuevisible
As mentioned above all types must be converted to strings. Allowed booleans are: "1", "0", "true", "false", "yes", "no", "y", "n". The strings are case-insensitive.
HTTP_200_OK
{
"id": "1",
"name": "R_0R0_0603_0.125W_1%",
"symbolIdStr": "Device:R",
"exclude_from_bom": "False",
"exclude_from_board": "False",
"exclude_from_sim": "True",
"fields": {
"footprint": {
"value": "Resistor_SMD:R_0603_1608Metric",
"visible": "False"
},
"datasheet": {
"value": "www.kicad.org",
"visible": "False"
},
"value": {
"value": "0R0"
},
"reference": {
"value": "R"
},
"description": {
"value": "I am a resistor",
"visible": "False"
},
"keywords": {
"value": "RES passive smd",
"visible": "False"
},
"custom1": {
"value": "MyText1",
"visible": "False"
},
"custom2": {
"value": "MyText2",
"visible": "False"
},
"custom3": {
"value": "MyText3",
"visible": "False"
}
}
}The API provides the functionality to include exclusion flags, as illustrated in the example above. These attributes serve to specify certain preferences within the KiCad software. The following exclusion flags are currently supported:
exclude_from_bom
exclude_from_board
exclude_from_sim
It’s important to note that if one ore more of these exclusion flags are not explicitly specified, KiCad will assume that they are not set for exclusion. In other words, the default behavior is to include all items and features in the relevant processes (BOM generation, board layout, and simulation) unless otherwise specified using these exclusion flags.
If KiCad receives anything else than HTTP 200, it will simply display an error message to the user and ignore that specific request result entirely. This means that KiCad could end up not displaying some or any categories or parts at all if the API does not comply.
Last Modified