-
Notifications
You must be signed in to change notification settings - Fork 23
Documentation
Welcome to the Commodore-Repair-Toolbox (CRT henceforward) 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. Though there can be many Excel files, it has only two levels:
- Level 1 (one file only)
- Main Excel data file with references for 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.
The level 1, main, data file is located in the same directory as the executable file and is named Commodore-Repair-Toolbox.xlsx.
The Excel file has only one worksheet, 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 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 executable file.
The 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 executable file.
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.
Typically the vendor concrete name of the component or a concrete value.
E.g. simple components like capacitors or resistors typically only have the value.
More complex components like IC's typically have their real printed name here.
Do note that Board label + Technical name or value + Friendly name is concatenated in the component list.
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.
Could be Capacitor, Resistor, IC, Connector, Misc or whatever else suits as a group identified for the component.
Will be shown in the component information popup.
Is a short contextual and relevant information about the component.
Could be technical information.
Must be one line only!
This is probably the hardest part of the data, because you need to have "not to little" and "not too much" information here.
Should have data that is relevant when working with the hardware, but not too much informational data.
You can have multi-lines here (ALT+ENTER for newline).
Direct reference from the Board schematics worksheet.
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.
Direct reference from the Components worksheet.
A board label can be referenced many times, as it can have multiple files per component.
This should (for now) be only 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.
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.
Path and filename to the image file.
The image format should be either JPG, PNG or GIF.
Use relative path from the executable file.
Direct reference from the Components worksheet.
A board label is most likely referenced many times, as it will have multiple scope readings per component.
This should (for now) be only PAL or NTSC to determine which region is relevant for this reading.
Doing oscilloscope measurements would be nice to know if this is done on a PAL or NTSC system.
Not actively used in application, but acts as an easy reference when viewing the Excel file.
Documents what is the expected reading on a working system.
Defines if the reading is expected to be Hz, LOW, HIGH or voltage.
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 executable file.
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 executable file.
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.
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 will be carried over from Excel to CRT
- E.g. a bold or colored text will only show the raw text
- All paths uses
/instead of\(to potentially better support Linux with Mono) - Similarly then treat filenames as case-sensitive (to potentially better support Linux with Mono)
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 Windows open source 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": 3a) In the left-side file panel, select the filename. 3b) Click the right-side link, "browser's file selector" and find the correct image file. 3c) 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: 9a) Do note that the downloaded Excel does NOT provide the correct value for the "Schematic name" column! 9b) You need to use the "Schematic name" from the worksheet "Board schematics" for that.