doc and sample for custom scripting

Author: psychogenic

README.md

@@ -331,16 +331,21 @@ will show you all the i/o ports you can play with.
 
 ## Initialization
 
-When the DemoBoard object is created, you _may_ give it a parameter to indicate how you intend to use it.  
 
-If not specifed, the value in [config.ini](src/config.ini) DEFAULT section `mode` will be used.
+Since only _one_ demoboard exists, in general it's safer and more efficient to use an accessor method to get ahold of the singleton:
 
+```
+tt = DemoBoard.get()
+```
+
+The first time this is used, the instance is created, using the `mode` setting in the DEFAULT section of [config.ini](src/config.ini) to define how it's being used (i.e. the RP2 driving the inputs or using external means).
 
+When the DemoBoard object is created, you _may_ give it a parameter to indicate how you intend to use it, rather than rely on config.ini.
 Possible values are:
 
 ```
 # use ini value
-tt = DemoBoard() # whatever was in DEFAULT.mode of config.ini
+tt = DemoBoard.get() # whatever was in DEFAULT.mode of config.ini
 
 
 # safe mode, the default
@@ -357,10 +362,10 @@ tt = DemoBoard(RPMode.ASIC_RP_CONTROL)
 # ASIC drives only management pins all else are inputs
 tt = DemoBoard(RPMode.ASIC_MANUAL_INPUTS) 
 
-
-
 ```
 
+and from that point on, you can use the `DemoBoard.get()` to access that object.
+
 If you've played with the pin mode (direction), you've loaded a project that modified the mode or you just want to change modes, you can set the attribute
 
 ```
@@ -369,6 +374,35 @@ If you've played with the pin mode (direction), you've loaded a project that mod
 tt.mode = RPMode.ASIC_RP_CONTROL
 ```
 
+
+### Write Your Own Script
+
+The default `main.py` does basic setup, reads the config.ini, loads the default project etc.  
+
+If you want to have some particular code run on boot, you can write your own script.  There's a little bit of required boilerplate to get this working, as the SDK needs to figure out which board it's running on and which carrier/chip is present.
+
+A full example that you can use for this is in [custom script main.py](./examples/custom_script_main.py), and you might want to start there.
+
+There are some useful hints in there, related to memory, logging and more, but the short of it is that what you really need is:
+
+```
+# to load the detector and demoboard modules
+
+from ttboard.boot.demoboard_detect import DemoboardDetect
+from ttboard.demoboard import DemoBoard
+
+# to first probe the board/breakout
+DemoboardDetect.probe()
+
+# and then get a handle to the DemoBoard object
+tt = DemoBoard.get()
+
+# pretty much it
+```
+
+See the [custom script main.py](./examples/custom_script_main.py) for all the details.
+
+
 ### Automatic Load and Default Config
 
 The [config.ini](src/config.ini) file has a **DEFAULT** section that may be used to specify the demo board mode, default project to enable and other things.

src/examples/custom_script_main.py

@@ -0,0 +1,83 @@
+'''
+Created on Nov 13, 2025
+
+Sample boilerplate for custom scripts
+
+
+@author: Pat Deegan
+@copyright: Copyright (C) 2025 Pat Deegan, https://psychogenic.com
+'''
+
+
+### Memory protection ###
+# Reading in a bunch of files tends to frag the memory
+# so we can set a low threshold on the garbage collector
+# here, and clean up post init
+import gc
+# stash the current value for garbage 
+GCThreshold = gc.threshold()
+# start very aggressive, to keep thing defragged
+# as we read in ini and JSON files, etc
+gc.threshold(80000)
+
+
+
+
+### Logging ###
+# uPython has no logging built-in, but we have an implementation 
+# that behaves nicely here, if you want it
+import ttboard.log as logging
+logging.basicConfig(level=logging.DEBUG)
+
+
+### TT demoboard ###
+# this is what you need to detect the board/shuttle and 
+# get access to the DemoBoard object
+from ttboard.boot.demoboard_detect import DemoboardDetect
+from ttboard.demoboard import DemoBoard
+# load anything else you need...
+
+
+# clean up memory
+gc.collect()
+# end by being so aggressive on collection
+gc.threshold(GCThreshold)
+
+
+
+
+### init code ###
+# some globals
+# logging handle
+log = logging.getLogger(__name__)
+# TT demoboard handle
+tt = None # instantiate this after probing
+
+# detect the board, carrier and shuttle
+if DemoboardDetect.probe():
+    log.info('Detected ' + DemoboardDetect.PCB_str())
+else:
+    log.error('Hm, could not figure out the DB/shuttle?')
+
+# create and access the TT demoboard singleton
+tt = DemoBoard.get()
+
+
+
+
+
+### user code ###
+# do whatever you like here
+# say load a project, set input byte and start clocking
+
+log.info("Loading factory test")
+tt.shuttle.tt_um_factory_test.enable()
+tt.ui_in = 1
+tt.clock_project_PWM(1e6)   # clock it at 1M
+
+print(tt.uo_out)
+
+
+
+
+

src/main.py

@@ -8,8 +8,9 @@
 
 If you want to use the SDK, all
 you really need is something like
-  
-      tt = DemoBoard()
+      
+      DemoboardDetect.probe()
+      tt = DemoBoard.get()
 
 Then you can 
     # enable test project
@@ -50,7 +51,7 @@ def startup():
     # construct DemoBoard
     # either pass an appropriate RPMode, e.g. RPMode.ASIC_RP_CONTROL
     # or have "mode = ASIC_RP_CONTROL" in ini DEFAULT section
-    ttdemoboard = DemoBoard()
+    ttdemoboard = DemoBoard.get()
     print("\n\n")
     print(f"The '{colors.color('tt', 'red')}' object is available.")
     print()