-
Notifications
You must be signed in to change notification settings - Fork 23
Documentation
Welcome to the Commodore-Repair-Toolbox (henceforward named CRT) documentation.
CRT has several data files, where it will read its various information from, like hardware, board, components, highlights and schematic images etc. The data files are all Excel, which is used as the data format, as this is fairly straightforward for the most to work with. The reason for having an easy format is, that hopefully many will contribute with either new or better data.
Though there can be many Excel files, it has only two levels:
- Level 1 (one file only)
- Main top-level Excel data file with references for the specific hardware/board data files
- Level 2 (multiple files)
- Hardware/board specific Excel data file having all detailed information about the hardware/board
Caution
Please do note that the data files have not yet reached its final maturity level, and by then its format could change in a nearby future release! Only relevant if you do your own data modification or use an older version.
The level 1, main top-level, data file is located in root folder of the Data folder and is named Commodore-Repair-Toolbox.xlsx.
The Excel file has only two worksheets so it is pretty simple.
These are the columns and how to understand them.
Exact same name as shown in the Hardware drop-down field in CRT.
The exact same hardware name can be represented on multiple rows, if it has different boards.
Keep the name short, so it can fit in the drop-down.
Exact same name as shown in the Board drop-down field in CRT.
The same board name should not be represented more than once per hardware.
Keep the name short, so it can fit in the drop-down.
Path and filename to the specific hardware/board Excel data file.
Use relative path from the Data folder.
Ignore this sheet, but it is used to determine if this Excel data file is compatible with the version from CRT. Sometimes the data format changes due to new or removed columns, and then it will show a warning, if there is a mismatch between the versions... to alert that it is probably a good idea to update the CRT application version and the Excel data files.
The level 2 Excel data file has quite a few worksheets, and this is the labor intense part, where all the relevant information needs to be.
Below is the documentation for each of these worksheets and the columns inside those.
Exact same name as shown in the thumbnail label.
Keep the name short, so it can fit in the label.
A schematic name must be unique in the board.
Also, the name is referenced in the worksheet Component highlights.
Path and filename to the schematic image file.
The image format should be either JPG, PNG or GIF.
Use relative path from the Data folder.
Which color to use for component highlighting in the schematic images, both in the "Main" image but also for the thumbnails.
All allowed colors are available here, https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0
Where relevant then use a semi-transparent gradient for the highlight, to allow viewing of potential information below the component highlight.
0% equals fully transparent.
100% equals solid non-transparent color.
Very short label representing the component name.
Ideally it should be 2-5 characters long only.
A component label must be unique.
Do note that Board label + Technical name or value + Friendly name is concatenated in the component list, so do consider to make this as short and precise as possible.
Typically components have "human readable" or "friendly" names.
Could also be that component is most often referred to as this name.
Should still be as short as possible.
Do note that Board label + Technical name or value + Friendly name is concatenated in the component list, so do consider to make this as short and precise as possible.
Typically the part-number from the vendor. In many cases there exists lists of part-numbers, so it can be a good reference, as often you can directly lookup technical details for a part-number.
Could be Capacitor, Resistor, IC, Connector, Misc or whatever else suits as a group identified for the component.
Keep the list short, so there is not many categories, but also do make sure to group it where it makes sense.
Should be either empty (blank), PAL or NTSC.
Use only a specific region (PAL or NTSC) when this component is specific for this region only.
Use empty (blank) when the component is generic, and for no specific region.
Will be shown in the component information popup.
Is a short contextual and relevant information about the component.
Could be technical information, which could not fit in "Technical name or value".
Must be one line only!
Direct reference from the Components worksheet.
A board label can be referenced many times, as it can have multiple files per component.
This should be either empty (blank), PAL or NTSC to determine which region is relevant for this image.
E.g. doing oscilloscope measurements would be nice to know if this is done on a PAL or NTSC system.
Also for e.g. the pinout image - does this show a PAL or NTSC component, as this could differ.
If the region is not relevant, then leave it blank.
Numeric/integer value.
If the image is for a specific component pin.
If the pin is not relevant, then leave it blank.
A pinout image should ideally show the legs and what is their input/output.
If an image is for a specific pin, then document its name for easy reference.
What value is expected here when measuring this with an oscilloscope?
This can different things like LOW, HIGH, Pulsing, a frequency or voltage.
Path and filename to the image file.
The image format should be either JPG, PNG or GIF.
Use relative path from the Data folder.
The note field for the image.
Typically (always?) the first image is the Pinout image, and this is special as the Note field is used for the component text in the "Resources" tab.
Direct reference from the Board schematics worksheet.
Must match exactly, so do remember to update here also, if you change the schematic name.
Direct reference from the Components worksheet.
A board label can be referenced many times per the same schematic name.
Location and dimension of rectangle.
Should be integer values.
View Introduction to labelling for how to create this data.
Component local files will show in both the Overview tab and the component information popup in CRT.
It is a local file specifically for this component - e.g. a datasheet or technical documentation.
Direct reference from the Components worksheet.
You can have multiple local files per component, so the board label is allowed to duplicate.
Name for the file that will be shown in CRT.
Path and filename to the local file.
The local file will be opened in whatever default application you have for the extension.
Use relative path from the Data folder.
Component URLs will show in both the Overview tab and the component information popup in CRT.
It is a URL specifically for this component - e.g. a technical documentation or troubleshooting references.
Direct reference from the Components worksheet.
You can have multiple links per component, so the board label is allowed to duplicate.
Name for the link that will be shown in CRT.
The URL will be opened in your default browser.
Board local files will show in the Ressources tab in CRT.
It is meant as a general documentation for the board - e.g. generic diagnosing or troubleshooting.
What kind of file is this - some examples are Troubleshooting, Technical documentation or alike.
You can have multiple local files per category, so the category name is allowed to duplicate.
Name for the file that will be shown in CRT.
Path and filename to the local file.
The local file will be opened in whatever default application you have for the extension.
Use relative path from the Data folder.
Board URLs will show in the Ressources tab in CRT.
It is meant as a general documentation for the board - e.g. generic diagnosing or troubleshooting.
What kind of URL is this - some examples are Troubleshooting, Technical documentation or alike.
You can have multiple URLs per category, so the category name is allowed to duplicate.
Name for the link that will be shown in CRT.
The URL will be opened in your default browser.
Will show who has contributed with data to this board.
Same as the main Excel data file.
There are a few important things to know generally for these Excel files.
- You should not have empty rows in the middle of your data, as this will be considered as "end of data"
- If there is a yellowish highlight in the data cell, it means the data needs to be validated or corrected
- If you have the answer for this, please let me know
- No formatting (colors, bold or italic etc.) will be carried over from Excel to CRT
- All paths uses
/instead of\(to better support Linux) - Similarly then treat filenames as case-sensitive (to potentially better support Linux with Mono)
- Check logfile after startup, as it will reveal any errors with the data files.
The data editing for the Excel files are pretty easy and is kind of "just do it", but the labelling (highlighting) of the components can be a little tricky, so hereby some documentation for how to do it.
For labelling the components in the schematics I have discovered the open source web application VGG Image Annotator version 2.0.12 (henceforward named VIA). The tool is quite handy and easy to use, once you learn its way of working. It will output a JSON file, which then can be converted into Excel format and this data can then be used directly in the level 2 data file, for the worksheet Component highlights.
- Inside the
Toolsfolder the VIA web application is located - open thevia.htmlfile in your browser. - Inside each
Data\{Hardware}\{Board}folder the JSON source files used for labelling are located.
- Find the VIA tool and open the file
via.htmlin your browser. - Open one of the JSON files in the
Data\{Hardware}\{Board}folder. -
VIA will now state that "File Not Found":
- In the left-side file panel, select the filename.
- Click the right-side link, "browser's file selector" and find the correct image file.
- It should now load the image and show all the labeling.
- Do your changes ...
- Save the VIA project file and overwrite the existing JSON file.
- Go to https://commodore-repair-toolbox.dk/convert-via-to-excel/ to convert the VIA JSON file to Excel.
- Upload the JSON file and download the Excel file it will provide.
- Copy/paste the data from the downloaded Excel file into the level 2 Excel file, in the worksheet
Component highlights:- Do note that the downloaded Excel does NOT provide the correct value for the "Schematic name" column!
- You need to use the "Schematic name" from the worksheet "Board schematics" for that.