This window provides a text editor for the JSON files that Pinscape Pico uses to specify and store the device's configuration settings.
For details on what goes in a configuration file, refer to:
There are two separate configuration files you can edit:
Safe Mode is particularly important when a crash occurs while the Pico is initializing. Without Safe Mode, a crash soon after reset could create an infinite loop of crashing, resetting, and crashing again, because whatever setting is causing the crash would just get restored again on every reset. That's extremely inconvenient, because you need the Pinscape software to be running in order to update its configuration file. If it just keep crashing over and over, you can't easily update the config file to fix (or at least disable) whatever was causing the crash. Safe Mode is meant to provide a stable environment that lets you at least inspect and update the configuration files.
There are no restrictions on what the Safe Mode configuration can contain. In fact, it can be a complete duplicate of the Main configuration if you want, but that would obviously defeat the purpose. The point is to minimize the features enabled, to minimize the things that can go wrong, while still allowing you to enable selected features of your choice.
The Config Tool comes with a few starter files that you can use to quickly populate the configuration, and then edit to match your specific customizations. The configuration editor will automatically offer to load one of these when the first time you connect to a newly installed Pico. You can also manually one of the template files at any time, via File > Import from Template File.
The template files are simply JSON text files stored in the ConfigTemplates folder within the main Config Tool program install folder, so you can inspect their contents with Notepad or any other Windows text editor if you want to take a look before importing them into the config editor.
The included template files are:
When you first open the editor window, it retrieves the current config file from the Pico and displays its contents.
After making changes, you can update the Pico with the new settings by going to the menu and selecting File > Save to Pico. The editor automatically checks the JSON code for syntax errors before sending it to the Pico, to avoid loading unusable config files onto the device. If no errors are detected, the editor transmits the file to the Pico for storage in the Pico's flash memory.
After saving the main configuration file, the Pico automatically reboots, so that the configuration changes are put into effect immediately. The Safe Mode configuration doesn't trigger an automatic reboot when saved, since that configuration is only used in post-crash situations.
If you want to discard your changes and reload what's currently stored on the Pico, select File > Reload from Pico. (You can also undo changes one-by-one via Edit > Undo.)
By default, the editor makes a local backup copy on disk each time you invoke Save to Pico. This is meant as a fail-safe against data loss in the event that something goes wrong with the Pico save, such as a USB disconnect, a Pico software crash, or the Config Tool itself carshing. Saving to the Pico overwrites the old copy of the configuration in the Pico's flash memory, so any unexpected interruption in the save process can leave an empty or truncated copy of the file on the Pico.
The local auto-backup copy provides an easy way to recovery if this ever happens. You can simply load the backup copy into the configuration editor using File > Import from File, and then use Save to Pico as normal.
You can disable the auto-backup feature using the Editor Preferences dialog. You can also change the folder location where the backups are saved, which defaults to a subfolder named AutoBackup within the Config Tool's main program install folder (see below).
The auto backup files have names of the form Config_PicoID_Date_Time, where PicoId is the hardware ID of the Pico. (Safe Mode configurations start with SafeMode_ in place of Config_.) The hardware ID is included to helps tell apart files belonging to different Picos, in case you're using more than one. The timestamps prevent a new file from overwriting an older file, in case you want to go back to an older version.
By default, the backup files are saved in the AutoBackup subfolder of the Config Tool's main program install folder. You can change this via Tools > Editor Preferences, where you can enter a different location in the Folder box.
The Folder path can be specified as a normal Windows path, but you can also use the following substitution variables:
Creating a backup copy on every save will eventually leave a lot of old versions in the backup folder. You can always delete unwanted old versions manually from time to time, but the Config Tool can automatically help with that if you like, by deleting versions older than a specified age. This is enabled by default, with a default maximum age of 30 days.
Automatic cleanup happens each time you launch the Config Tool. It doesn't require any interaction; the program simply looks for files in the Auto Backup folder older than the specified maximum age and deletes them. It only deletes files as follows:
You can disable automatic cleanup entirely, or change the maximum number of days before deletion, via the Tools > Editor Preferences command.
File > Save a Copy As lets you save the current editor window contents to a local file on your Windows system. The command prompts you for the name and location of the saved file with a normal Windows file selection dialog.
This is useful if you want to save a backup copy or a snapshot of the configuration on your Windows system. It also gives you an easy way to load the configuration text into an external text editor program, if you'd prefer to work on it with a different editor.
File > Import from File does the opposite of Save As, loading a local Windows file into the editor window. The loaded file replaces the entire current contents of the window. You can use this to restore a saved backup copy, or to update the Pico with changes you've made to the exported file through an external text editor program or other tools.
If you'd prefer to routinely work on the Pinscape config files using a stand-alone text editor program, rather than the editor built into the Config Tool, it might be more convenient to set up some macros in your editor that invoke the separate command-line version of the Config Tool to load and save the JSON file directly from the Pico. Most good programmer's text editors provide macro capabilities that let you automate the interface between the editor and external command-line tools, so that the editor can send and retrieve files through external processors, such as sending a file to a compiler and reading back error messages. The command-line Config Tool's --get-config and --put-config options should be suitable for use with that kind of macro interface. The suggested procedure:
The editor keeps track of the section you're currently working on, showing the current property name on the right side of the top control bar. Click on the property name to go to the documentation reference section for that property.
The drop arrow next to the property brings up a menu of all of the top-level property sections defined in the file so far. Select one of the menu items to navigate straight to that section.
As you type, the editor will attempt to provide suggestions based on the current context. If you start typing a property name, the editor will pop up a list of all of the property names that it thinks are valid in the current context. If you're typing a value, and the current property has a limited set of valid choices, the editor will pop up a list of the allowed values.
When a list pops up, you can select an entry with the mouse or by pressing Tab or Enter, and you can change the selection with the up and down arrow keys. That lets you enter a property name by just typing its first few letters to find it in the list.
If you want to cancel the pop-up list, just press Escape or backspace. You can also just keep typing and pretend the list isn't there. The list will go away on its own when you type a non-symbol character such as ":" or ",".
If you find auto-complete overly intrusive or annoying, you can disable it via the Editor Preferences dialog.
File > Check for Errors runs a JSON syntax check on the file. If any errors are found, the program displays a list of errors in a panel below the editor window. Double-click on a message in the error list to jump to the location in the source text.
If the syntax check succeeds, the command proceeds to check the file against the JSON "schema", which is the set of rules governing which property names are allowed, which are required, and what values they can have. The error panel will appear with a list of any problems detected. Double-click on a message in the error list to jump to the source location.
Many schema rule violations are relatively benign. It's always harmless to add an extra property that the firmware doesn't know about, for example, since the firmware will just ignore any properties it doesn't recognize. However, an unknown property is often a sign that you entered a property name incorrectly, such as getting the upper/lower case mix in a name wrong (since JSON is strictly case-sensitive). So it's best to assume that any errors listed are important, and make sure you understand them before you dismiss them as just another computer program being overly fussy.
Missing "required" properties are more problematic than extra unrecognized properties, because the firmware won't usually be able to configure a device or feature without all of the required settings for that feature. For example, if you don't tell the status LED device (rgbStatusLight) which GPIOs are connected to the LED color channels, the firmware won't know how to address the LED, so the LED won't function at all. However, this is still relatively harmless in the big picture, since the missing information will only affect that one device or option; a non-working status LED won't prevent the button inputs from working, for example.
The schema rules are programmed into the Config Tool, so they're not necessarily 100% identical to the actual rules that the firmware uses when it reads the configuration. There might be some differences especially if you're using a version of the firmware that's newer or older than your Config Tool version, since new properties might be added in newer firmware versions. It's always best to check the device message log after making any changes to make sure that the firmware is interpreting the settings as you intended and that they're working properly. The schema check is only meant to be a quick way of checking for superficial errors, such as typos in the property names.
The Save to Pico command always automatically runs a syntax check before committing the file to the Pico, and it won't update the Pico unless the syntax check passes. Invalid syntax would effectively revert the Pico back to entirely default settings by making the JSON unusable, which you probably wouldn't want.
Optionally, Save to Pico can also run a schema rules check. You can control whether or not the rules check happens via the Editor Preferences dialog. If the rules check finds any errors, the editor will prompt you (via a dialog) whether you want to program the Pico anyway, or review the errors without saving. The editor gives you the option to save the updates even if there are schema rules violations, because the rest of the JSON is usually still usable. Most rules violations only affect the particular option they apply to, and don't interfere with any other settings.
The Find box in the toolbar at the top of the editor window lets you do simple literal-text searches. This quick-find control searches incrementally as you enter text, so you can see the next match immediately. Press Return to end the search and stay on the matched text; press Escape to cancel the search and return to the original cursor position.
For more powerful search options, use the Edit > Find and Replace menu command. This gives you options to search by exact case, whole words, and regular expressions. It also can automatically replace matches with new text.
The Find and Replace dialog has a few extra options for your search.
For example, suppose you un-check Match Case, check Preserve Case, enter gpioport in the Find What box, and type outputPin in the Replace With box. Here's how the replacement will work for various matches:
| Original text | New text after replacement | Explanation |
|---|---|---|
| GPIOPORT: 7 | OUTPUTPIN: 7 | Original is all caps, so replacement is converted to all caps |
| gpioport: 7 | outputpin: 7 | Original is all lower case, so replacement is converted to all lower case |
| gpioPort: 7 | outputPin: 7 | Original is mixed case, so the Replace With text is used exactly as entered |
| GpioPort: 7 | OutputPin: 7 | Original is mixed case with the first letter capitalized, so the Replace With text's first letter is capitalized |
If you don't check Preserve Case, the result is much simpler: every case is replaced with the exact text in the Replace With box, outputPin, in that exact mix of upper and lower case.
The Find-and-Replace dialog lets you search by literal text or by regular expression patterns. Tick the Regular Expression checkbox to enable regular expression searching.
The regular expression grammar is the one implemented in the standard C++11 compiler library, for which you can find the full technical details in many C++ language references, such as https://en.cppreference.com/w/cpp/regex/ecmascript. You can also rely pretty well on any manual covering standard Javascript regular expressions, since the C++ and Javascript grammars are almost exactly the same. Here's a very quick summary of the elements I use most often:
| Symbol | Meaning |
|---|---|
| . | Match any single character (except newlines) |
| ? | Match the preceding symbol zero or once |
| * | Match the preceding symbol zero or more times: x* matches zero or more x's, .* matches any string |
| + | Match the preceding symbol one or more times |
| {m,n} | Match the preceding symbol at least m times and at most n times |
| ( ) | Groups text for operators: (abc)+ matches the sequence abc one or more times; also creates a back-reference that you can use in a substitution in the Replace With text |
| [ ] | Matches any single character listed inside the brackets: [0123457] matches one octal digit; you can also use ranges, such as [0-7] or [a-z], and exclusions, as in [^a-z] (match any single character except a to z) |
| | | An "OR" that matches the expressions on either side of the bar: abc|def matches either abc or def |
| \d | Matches a single digit |
| \d | Matches a single non-digit |
| \w | Matches a single word character (alphabetic, digit) |
| \W | Matches any single character that's not a word character |
| \s | Matches a single space, tab, or other whitespace character |
| \S | Matches any single character that's not whitespace |
| \b | Matches a position at the start or end of a word (this is an "assertion" that matches a position in the source text, without using up any of the characters of the source text |
| ^ | Matches the beginning of a line |
| $ | Matches the end of a line |
| \B | Matches a position that's not at the start or end of a word |
| \. \* \? \+ \( \) \[ \] \| \\ \{ \} \^ \$ | Putting a backslash, \, in front of one of the special symbols removes its specialness, making it literally match the special character; so \( matches an open paren, \* matches an asterisk, \\ matches a backslash, and so on |
There are some other more advanced features, such as non-greedy quantifiers (??, +?, *?, {m,n}?), positive and negative assertions, named character classes, and back-references, that you can read about in a C++ or Javascript reference guide.
When you enable regular expressions in the search box, you also get a special feature for the replacement text called "back-references". A back-reference is the portion of the original text that matched a parenthesized section of the regular expression. You can substitute the back-reference text into the replacement text, using the special codes \1, \2, \3, and so on. When the replacement is carried out, \1 in the Replace With text is replaced with the original text in the buffer that matches the first parenthesized portion of the Find What regular expression, \2 is replaced with the second parenthesized group match, and so on.
You can also use \0 to substitute the entire matching source text.
For example, the search term gpio:(\d+), will match the literal text "gpio:" followed by a string of decimal digits. The replacement text port:\1 will replace each occurrence with the string "port:" followed by the same digit string from the original text, so "gpio:7" will become "port:7" and "gpio:12" will become "port:12".
The print options should be self-explanatory (or at least familiar enough, if you've ever used any other Windows programs), except that the Header and Footer settings in the Page Setup options have some extra hidden features.
First, the header and footer each let you set up three sections, for text that's aligned at the left, center, and right side of the page. Separate the sections with the vertical bar symbol, "|".
This part is at the left|This is centered|This is at the right
If there are only two parts, they're aligned left and right:
This part is at the left|This part is at the right
If you want to include a vertical bar character literally in the header/footer text printed on the page, type it twice: ||.
Second, there are several substitution variables that you can use, written as $(name). The substitution variables are:
The JSON editor has a preference setting for Emacs-style key bindings. Emacs is an old text editor that's mostly used by Linux C++ programmers, so I don't expect there's much overlap with Windows virtual pin cab builders, but I know there's at least one example (me).
When you enable Emacs mode, the Configuration Editor uses key bindings that match the basic set of keys Emacs uses for cursor navigation and simple editing operations. It's not even remotely a complete Emacs emulation, and it doesn't have any of Emacs's advanced features or scripting capabilities. For the most part, it's just a remapping of the keyboard for people who prefer using the Emacs-style key bindings, with a few tweaks to the UI behavior to better match the Emacs idioms. But it doesn't add any new features or capabilities; it's just the same editor with different key assignments.
| Key sequence | Command |
|---|---|
| Ctrl+A | Start of line |
| Ctrl+B | Cursor left ("back") |
| Ctrl+C | Copy |
| Ctrl+D | Delete character |
| Ctrl+E | End of line |
| Ctrl+F | Cursor right ("forward") |
| Ctrl+G | Cancel selection mode/cancel search |
| Ctrl+K | Delete to end of line ("kill") |
| Ctrl+L | Scroll to center the cursor on screen |
| Ctrl+N | Cursor down ("next line") |
| Ctrl+O | Open the line here by inserting a newline after the cursor |
| Ctrl+P | Cursor up ("previous line") |
| Ctrl+R | Reverse search |
| Ctrl+S | Search |
| Ctrl+T | Transpose characters at caret |
| Ctrl+V | Page down |
| Alt+W | Page up |
| Esc W | Page up |
| Ctrl+W | Cut selection |
| Esc W | Copy selection |
| Alt+W | Copy selection |
| Ctrl+Y | Paste last cut/copy ("yank") |
| Ctrl+Z | Scroll down a line |
| Alt+Z | Scroll up a line |
| Esc Z | Scroll up a line |
| Ctrl+Space | Set the selection starting point |
| Ctrl+_ | Go to line number |
| Ctrl+[ | Check for errors |
| Alt+% | Search and replace |
| Esc % | Search and replace |
| Esc < | Go to top of file |
| Alt+< | Go to top of file |
| Esc > | Go to end of file |
| Alt+> | Go to end of file |
| F1 | Help |
| F3 | Find Next |
| Shift+F3 | Find Previous |
| F12 | Save to a local file |
| Ctrl+F9 | Undo |
| Ctrl+F10 | Redo |
| Ctrl+X G | Go to line number |
| Ctrl+X H | Select All |
| Ctrl+X R | Redo |
| Ctrl+X U | Undo |
| Ctrl+X Ctrl+F | Import from file |
| Ctrl+X Ctrl+R | Reload from Pico |
| Ctrl+X Ctrl+S | Save to Pico |
| Ctrl+X Ctrl+W | Write to file |
| Ctrl+X Ctrl+X | Move cursor to other end of selection |