girish

Vim Plugin using Vim9 Script

2023-08-03T08:16:45+00:00

If you are a longtime user of Vim there are occasions where you may want to extend the functionality of Vim by writing your own plugin. The release of Vim9 script has made the task less intimidating since the new scripting language resembles Python. This blog post is not a beginner guide but rather a collection of thoughts from my experience developing autosuggest and vimcomplete.

If you are on the fence deciding whether to implement your idea in Lua for Neovim or Vim9script for Vim, I have some opinions. Even though legacy Vim script works on both Vim and Neovim I intentionally did not learn it because, well, it is just weird and unreadable.

Both Lua and Vim9script are compiled into bytecode (unlike legacy script). I wrote a few non-trivial plugins in Lua before switching over to Vim9script. I prefer the latter because the code tends to be more compact, has more advanced language features for functional programming, has better regex support, and offers smoother interface to Vim’s APIs. But Lua is its own fun language to program in and Neovim keeps experimenting with new features. Ultimately it boils down to preference. If Vim9script tickles your curiosity then read on.

Directory Structure

The first step in writing a plugin is to organize your folders. Vim expects certain folder names. Here is a typical organization for github hosted repositories.

myplugin
├── LICENSE
├── README.md
├── autoload
│   ├── foo.vim
│   └── bar.vim
├── doc
│   └── myplugin.txt
└── plugin
    └── myplugin.vim

Your main directory name should be the name of the plugin. Under that directory, the plugin should have a plugin and an autoload directory:

The plugin directory sets up the plugin. It should include the commands and keybindings that you want in your plugin. The files in this directory are sourced in alphabetically order (:h load-plugins).
The autoload directory holds the meat of the plugin. It is only loaded when one of the commands defined in the plugin directory gets called. On-demand loading keeps Vim’s initialization faster.
doc directory is optional but highly recommended. Learn the Vim help file syntax. You could include even more information here than in README.md.
In addition, you may need an import directory if you wish to export functions for use in other plugins.

Note: Vim has extensive documentation. Anytime you have doubt over foo try :helpgrep foo or :h foo<tab> (with wildmenu) or use autosuggest.

Include the following boilerplate code at the top of plugin/myplugin.vim.

if !has('vim9script') ||  v:version < 900
    " Needs Vim version 9.0 and above
    finish
endif
vim9script
g:loaded_myplugin = true

All other files should include vim9script at the top. In order to use functions defined in another script you have to use the import directive. From a script in plugin directory you could define a command as follows.

import autoload '../autoload/foo.vim'
command! -nargs=0 MyCommand foo.SomeFunction()

In the above example, SomeFunction() needs to be exported (:h vim9-export) from foo.vim.

Also, make use of User (:h User) auto-command event to synchronize parts of initialization.

Language Features

Vim9script is fairly easy to learn. You can also pick up some advanced insights here. If you are familiar with Python there is VimScript For Python Developers. Finally, here are some suggestions to make your programming task more fun.

Lambda Expressions

If you are doing any type of data manipulation lambda expressions (:h lambda) come in handy. You can use them with usual suspects filter(), map(), reduce(), sort() etc.

Functions can be chained using -> operator. Use the arg->func() idiom consistently throughout. Keep your code readable and bloat-free.

Meta Tables

Vim9script will have class (:h class) in the near future. In the meantime, you can emulate an object (encapsulation) using a simple dictionary and function references (:h funcref(), :h function()).

def NewMyObject(someArg: bool): dict<any>
    var contents = {
        property1: [],
        property2: someArg,
    }
    contents->extend({
        functionName1: function(FunctionName1, [contents]),
    })
    return contents
enddef

def functionName1(obj: dict<any>, optionalArg: number)
    var foo = obj.property1
enddef

var myObj = NewMyObject(true)
var fnArg = 22
myObj.functionName1(fnArg)

Options

Users of your plugin may need to set options. Use a dictionary to encapsulate all options. It is best not to use a global variable for each option, since they pollute global namespace. You can use a global function that takes a dictionary argument to set the options. There is also a possibility to use exported function, but this limits the users to only use Vim9script for configuration. So the former method is preferred.

In your autoload/options.vim you can define the options.

export var myOptions: dict<any> = {
    option1: '',
    option2: false,
    option3: [],
}

In plugin/myplugin.vim define a global function to set options.

import autoload '../autoload/options.vim'

def! g:PluginNameOptionsSet(opts: dict<any>)
    options.myOptions->extend(opts)
enddef

Strings

Be familiar with ==#, ==?, =~#, =~?, !~, match(), matchstr(), matchlist(), \c, \v, " vs ' etc. See help files.

Use $'sometext {var}' as opposed to "sometext " .. var.

Debug

For the most part echom in scripts is adequate. You can view the messages using :messages. For checking regex you can use :echo 'teststring' =~ 'pattern' or :echo matchstr('foo', 'pattern').

Disassemble

Sometimes you may ask yourself if it is worth caching a dictionary key value outside a loop, and discover that Vim9 compiler does not do loop optimization. You can verify using :disassembly that it uses LOADSCRIPT and USEDICT instructions inside the loop when value is not cached.

% vim -Nu NONE -S <(cat <<'EOF'                                                                                       1 :(   
    vim9script
    var foo = {x: 1, y: 2}
    def Func()
        var fooy = foo.y
        for i in range(5)
            # echom fooy     # good: using cached value
            echom foo.y      # not good
        endfor
    enddef
    disa Func
EOF
)

Asynchronous Execution

Vim offers job_start() for truly parallel execution (on a multicore system). You can spawn a new process and wait for output. However, there is also a lightweight option that offers concurrent execution. It may sound non-intuitive but you can use timer_start() with 0 timeout to schedule your function for execution at a later time when Vim’s main-loop is free. You can also pass arguments to callback, for example, timer_start(0, function(MyWorker, [arg1, arg2])). Typically you break down your long running task into batches (say you want to search a few thousand lines then search in batches of a thousand lines each). Each batch can be scheduled using timer_start() as above, with one of the arguments to MyWorker() being the index into a batch data array. These tasks should be chained by having MyWorker() call the next timer_start() (for the next batch). The magic here is that Vim schedules any newly typed keystrokes between each MyWorker() invocation. Even though Vim is single-threaded your plugin remains responsive to keystrokes even while working on a long running task.

For demonstration, see autosuggest or ngram-complete.

Performance Measurement and Timing

Calling reltime() before and after a code section measures execution time.

var start = reltime()
# ... do something ...
echom $'Elapsed time: {start->reltime()->reltimestr()}'

You can abort a task if it goes over a timeout. Use reltimefloat() for that.

const timeout = 2000 # millisec
var start = reltime()
while (start->reltime()->reltimefloat() * 1000) < timeout
    # ... process a batch ...
endwhile

Expose APIs to Other Plugins

Say you want other plugins to be able to call FooAPI() function of your plugin. Create a directory named import at the top level and a file inside it (say fooplugin.vim). Inside this file you can expose your APIs by exporting functions.

vim9script
import '../autoload/myfoo.vim'

export def FooAPI()
    myfoo.MyService()
enddef

Other plugins can import your API.

import 'fooplugin.vim'
def MyFunc()
    fooplugin.FooAPI()
enddef

For demonstration, see API in vimcomplete used in ngram-complete.

Autocompletion for Vim9 Script

LSP for Vim9 script does not exist yet. In the meantime, you can use the autocompletion extension for Vim9 script language vimscript-complete.

Keyboard: How Quickly Can You Press a Key

2023-01-16T08:16:45+00:00

If you ever wondered whether a key-press happens in milliseconds or microseconds in a keyboard wonder no more.

TLDR; It takes several milliseconds depending on the switch and finger speed.

What is measured?

A switch has pre-activation (pre-travel), activation and post-activation distance. In case of Gateron Yellow optical switches, so called ‘speed’ switches, pre-activation is about 1mm, activation happens for another 1mm (height of optical elements) and post-activation distance is about 1.2mm. For other Gateron MX style switches pre-activation is 2mm, activation is 1mm, and post-activation is 2mm. Since the setup uses voltage waveform from an optical switch as a trigger only the activation process is subject to measurement. Time taken for pre-activation and post-activation are not accounted for. Secondly, the switch actuator does not have to travel all the way through the actuation zone for the state change to be registered in the microcontroller. The GPIO pin registers a “high” when voltage rises to ~0.8V and “low” when voltage falls below ~2V.

Setup

The test setup consists of a highly responsive optical switch. The phototransistor has rise and fall time of a few nanoseconds. You can verify from the oscilloscope screen. Yellow line represents voltage drop across the phototransistor while green line is the pulse applied to IR LED. Voltage drop across phototransistor is inverted owing to the nature of the circuit. Each horizontal division is 1us.

Before measuring key-press time IR LED is driven from a constant voltage source. When key is pressed IR light is interrupted from entering the base junction of phototransistor. This corresponds to fall time and since the plot is reversed the yellow line rises.

The switch used is of Gateron Yellow optical linear variety. About 10 measurements are taken but only a representative sample is presented here.

Fast Key Press

It takes about 100us for fall time. Each horizontal division is 100us and vertical division is 2V. Voltage rises from ~0V to ~3.3V. You can observe that voltage rises very quickly to 0.8V, in less than 50us. This is when GPIO pin will register state change. These types of fast key-presses are rare in normal typing though.

Average Key Press

It takes about 200us to 2ms. Each horizontal division is 100us and vertical division is 2V as above. Normal typing could be characterized as average.

Lazy Key Press

It takes over 2ms. Each horizontal division is 1ms and vertical division is 2V. This is generally rare for switch with lighter springs but quite common for switch with heavier springs.

Average Key Release

It takes about the same time as key press. Each horizontal division is 100us.

Note

Although no serious statistical evidence is compiled and sample size is just one, averaging over 10 key-presses a switch with lighter spring (15gf) resulted in faster key-presses compared to heavier Yellow (35gf) and Red (45gf) switches.
With 15gf it is possible (although rare) to get sub 100us key-presses.

There is generally a clean rise and fall curve of voltage drop across phototransistor. This is the reason why optical keyboards do not require debouncing. Even though there is a transition region of voltage (0.8v-1.2v) where GPIO pin can read unpredictable logical value, it is generally not the case. If such problem indeed was encountered a comparator with hysteresis (Schmitt trigger) can be added to the circuit.
How fast can an optical switch detect a key-press? As you may have noticed the optical switch used in this experiment has extremely low rise/fall time. So the key event is detected as soon as the voltage crosses TTL logic threshold. The switch uses about 2mA current (for IR LED and phototransistor combined). Given that USB can supply 500mA, all the switches in the keyboard can remain powered up all the time. This linear (non-switched) circuit is only limited by how soon the microprocessor can read the GPIO pins. On Nordic’s nrf52840 MPU a tight loop can read GPIO ‘ports’ (which contain a group of GPIO pins) all at once at 460kHz frequency (see pic). Suffice to say an optical switch will not be on the critical path.

This test does not measure keyboard latency. After the microprocessor detects state change event it has to ship the data to the host computer. Since keyboards are usually configured as HID there will be at least 125us polling delay if the USB port is configured as HS (high speed) USB or (most likely the case) 1ms delay if port is FS (full speed) USB. The application on the host computer will have additional delay as well.

UPDATED Jan 21, 2023

After the above experiment I was curious to find out if the voltage across phototransistor changes throughout the 1mm height through which the switch actuator travels while closing the aperture available for IR light to pass through. The result might surprise you. I used the above setup but changed the input pin to ADC (analog to digital converter). When the actuator is pressed, voltage slowly rises from 0V to 3.3V. The ADC on nRF52840 is capable of 16 bit measurement, which provides adequate resolution.

IR light from LED is so narrow that only about 0.1mm to 0.2mm distance of actuator actually participates in voltage change.

This is a far cry from 1mm of actuation distance that was anticipated. As the key is pressed voltage remains at 0V until the critical distance of 0.1mm to 0.2mm through which voltage suddenly rises to 3.3V. This spot is at the same height as the center of the IR lens. All the key-press numbers measured above are relevant for only 0.1mm to 0.2mm of actual key travel. Let’s say it took 200us to travel 0.2mm distance. This translates to finger speed of 1m/s – not unreasonable.

Instead of referring to actuation distance we can call this actuation point. This point is about 1.5mm from the top of the switch for Gateron Yellow and about 2.5mm for Gateron Red optical switches. Finger do not travel at a constant speed. It accelerates from standing start. One can guess that it would take 1ms to over 2ms to register a key-press event from the moment finger starts moving, in an optical switch setup with infinitesimal (nanoseconds) rise time. In a mechanical switch (with electrical contacts), there is additional 5ms to 7ms delay owing to debouncing.

Conclusion

It would take 1ms to over 2ms to register a key-press event from the moment finger starts moving, in an optical switch setup with infinitesimal (nanoseconds) rise time.

GPIO and ADC setup for Seeed XIOA BLE

KiCad 6 Python Scripting: Place Footprints, Create Tracks, Curved Tracks, Vias, and Edge Cut Lines

2022-08-17T10:16:45+00:00

If you find yourself in a situation where you are placing component footprints at multiple locations on PCB using KiCad, or routing a pattern of tracks repeatedly (like in a keyboard) you’ll save time by automating through a Python script.

Introduction
- How to Run Python Script
- KiCad Coordinate System
Footprints
- Place Footprint
Tracks
Edge Cuts

Introduction

KiCad 6 has decent support for scripting but documentation can be hard to grok. Reading their code is often the only recourse. I’ll cover the basics of placing footprints and routing tracks with code examples.

How to Run Python Script

Copy (or symlink) your python script to KiCad plugins directory, which (on a Mac) is located in ~/Documents/KiCad/6.0/scripting/plugins. You can find out where KiCad looks for plugins and scripts by running import pcbnew; print(pcbnew.PLUGIN_DIRECTORIES_SEARCH) from Python Console in PCB Editor window (icon is at the right hand top corner).

In the console window simply import the python module using import filename (if your python script is named filename.py). This will execute the script. It works the first time, but Python interpreter will not import the same module twice. There is a solution. You reload the module again using import importlib followed by importlib.reload(filename).

There is an alternate approach of using plugins, but above method is simpler; your print output appears in the console window instead of having it redirected to a file.

KiCad Coordinate System

The Cartesian plane KiCad uses has Y-axis pointing down and X-axis pointing to the right. Moreover, distance is specified in millionth of millimeter, and angles are in tenths of a degree. These aspects will become clear later. Points in space are represented by wxPoint. There is also a millimeter variant called wxPointMM, and a conversion routine fromMM(). Using mils instead of millimeter is also possible but not covered here.

Footprints

Footprints are needed to position components on pcb.

Place Footprint

Get a reference to the footprint object from the Board object. You can then place the footprint and set the orientation by calling the footprint object itself.

In the following example we have three (SMD) footprints, for 2 resistors and a diode.

import pcbnew
from pcbnew import wxPoint, wxPointMM

board = pcbnew.GetBoard()

# Get reference to footprint objects
board = pcbnew.GetBoard()
r1 = board.FindFootprintByReference("R1")
r2 = board.FindFootprintByReference("R2")
d1 = board.FindFootprintByReference("D1")
assert(r1 and r2 and d1)

# Place footprints
r1.SetPosition(wxPointMM(20, 20))    # (x, y) = (20, 20) in mm
r1.SetOrientation(90 * 10)           # rotate by 90 deg
r2.SetPosition(wxPointMM(25, 21))
d1.SetPosition(wxPointMM(23, 26))

# Update display
pcbnew.Refresh()

Tracks

KiCad 6 supports straight line as well as curved tracks.

Straight Track

To route a track, you need a start and end point. You need to also locate the center of the pads that terminate the track.

import pcbnew
from pcbnew import wxPoint, wxPointMM

def add_track(start, end, layer=pcbnew.F_Cu):
    board = pcbnew.GetBoard()
    track = pcbnew.PCB_TRACK(board)
    track.SetStart(start)
    track.SetEnd(end)
    track.SetWidth(int(0.25 * 1e6))
    track.SetLayer(layer)
    board.Add(track)

# Route track from pad #1 of footprint R1 to pad #1 of D1 with 45-deg corner
board = pcbnew.GetBoard()
start = board.FindFootprintByReference("R1").FindPadByNumber("1").GetCenter()
end = board.FindFootprintByReference("D1").FindPadByNumber("1").GetCenter()
offset = end.x - start.x
thru = pcbnew.wxPoint(start.x, end.y - offset)
add_track(start, thru)
add_track(thru, end)

pcbnew.Refresh()

Curved Track

KiCad 6 has support for drawing curved tracks, be it circular arcs or Bezier curves. Only circular arcs are covered here. Use PCB_ARC object and specify start, mid and end points of arc.

For low frequency applications, curved tracks are mostly for aesthetic reasons. Moreover, during manual routing if you use the “shove” option KiCad may decide to convert rounded edges to sharp corners. To manually route a rounded track use Ctrl-/ (or Cmd-/ on Mac) shortcut to switch among following options: corners at 45 deg -> rounded corners at 45 deg -> corners at 90 deg -> rounded corners at 90 deg, after you click on the starting point of track.

The following example adds a rounded corner to two straight line tracks.

import pcbnew
import math
from pcbnew import wxPoint, wxPointMM

def add_track_arc(start, mid, end, layer=pcbnew.F_Cu):
    board = pcbnew.GetBoard()
    track = pcbnew.PCB_ARC(board)
    track.SetStart(start)
    track.SetMid(mid)
    track.SetEnd(end)
    track.SetWidth(int(0.25 * 1e6))
    track.SetLayer(layer)
    board.Add(track)

# Route track from pad #2 of footprint R1 to pad #1 of R2
#   with 90-deg arc of radius 1.5mm
board = pcbnew.GetBoard()
radius = 1.5 * pcbnew.IU_PER_MM
start = board.FindFootprintByReference("R1").FindPadByNumber("2").GetCenter()
end = board.FindFootprintByReference("R2").FindPadByNumber("1").GetCenter()
start1 = pcbnew.wxPoint(end.x - radius, start.y)
add_track(start, start1)
end1 = pcbnew.wxPoint(end.x, start.y + radius)
add_track(end1, end)
# Find the mid point of the arc by translating the origin to the center of arc
#   and rotating the axis by 45-deg
theta = 45
mid = wxPoint(
    start1.x + radius * math.cos(math.radians(theta)),
    end1.y - radius * math.sin(math.radians(theta)),
)
add_track_arc(start1, mid, end1)

pcbnew.Refresh()

Create Via

Create a via at 1mm offset from pad #2 of footprint R2 and connect a track to it.

import pcbnew
from pcbnew import wxPoint, wxPointMM
 
board = pcbnew.GetBoard()
pad = board.FindFootprintByReference("R2").FindPadByNumber("2").GetCenter()
via_location = wxPoint(pad.x + 1 * pcbnew.IU_PER_MM, pad.y)
add_track(pad, via_location)
via = pcbnew.PCB_VIA(board)
via.SetPosition(via_location)
via.SetDrill(int(0.4 * 1e6))
via.SetWidth(int(0.8 * 1e6))
board.Add(via)

pcbnew.Refresh()

Remove All Tracks and Vias

You may need to remove stale tracks before adding new ones.

import pcbnew

board = pcbnew.GetBoard()
for t in board.GetTracks():
    board.Delete(t)

pcbnew.Refresh()

Edge Cuts

Edge Cut lines define the boundary of the pcb. KiCad 6 has support for drawing straight lines and arcs on any layer, not just on Edge Cuts. To draw a line you specify the end points. To draw an arc you specify starting point, center of the arc, and the angle. This API is slightly different from drawing curved tracks where you specify mid-point of the curve. There is also API to draw Bezier curves.

Draw Line

Use PCB_SHAPE object and set the shape to SHAPE_T_SEGMENT. You can specify the layer and line width. Use the search box in the documentation to search for symbols.

Add an edge cuts border around the components. Draw lines on all four sides and connect them by rounded corners.

import pcbnew
from pcbnew import wxPoint, wxPointMM

def add_line(start, end, layer=pcbnew.Edge_Cuts):
    board = pcbnew.GetBoard()
    segment = pcbnew.PCB_SHAPE(board)
    segment.SetShape(pcbnew.SHAPE_T_SEGMENT)
    segment.SetStart(start)
    segment.SetEnd(end)
    segment.SetLayer(layer)
    segment.SetWidth(int(0.1 * pcbnew.IU_PER_MM))
    board.Add(segment)

board = pcbnew.GetBoard()
border = 4 * pcbnew.IU_PER_MM
radius = 1 * pcbnew.IU_PER_MM
r1 = board.FindFootprintByReference("R1").GetPosition()
r2 = board.FindFootprintByReference("R2").GetPosition()
d1 = board.FindFootprintByReference("D1").GetPosition()
start = wxPoint(r1.x - border + radius, r1.y - border)
end = wxPoint(r2.x + border - radius, r1.y - border)
add_line(start, end)
start = wxPoint(end.x + radius, end.y + radius)
end = wxPoint(start.x, d1.y + border - radius)
add_line(start, end)
start = wxPoint(end.x - radius, end.y + radius)
end = wxPoint(r1.x - border + radius, start.y)
add_line(start, end)
start = wxPoint(end.x - radius, end.y - radius)
end = wxPoint(start.x, r1.x - border + radius)
add_line(start, end)

pcbnew.Refresh()

Draw Arc

Use PCB_SHAPE object and set the shape to SHAPE_T_ARC.

import pcbnew
from pcbnew import wxPoint, wxPointMM

def add_line_arc(start, center, angle=90, layer=pcbnew.Edge_Cuts):
    board = pcbnew.GetBoard()
    arc = pcbnew.PCB_SHAPE(board)
    arc.SetShape(pcbnew.SHAPE_T_ARC)
    arc.SetStart(start)
    arc.SetCenter(center)
    arc.SetArcAngleAndEnd(angle * 10, False)
    arc.SetLayer(layer)
    arc.SetWidth(int(0.1 * pcbnew.IU_PER_MM))
    board.Add(arc)

board = pcbnew.GetBoard()
border = 4 * pcbnew.IU_PER_MM
radius = 1 * pcbnew.IU_PER_MM
r1 = board.FindFootprintByReference("R1").GetPosition()
r2 = board.FindFootprintByReference("R2").GetPosition()
d1 = board.FindFootprintByReference("D1").GetPosition()
start = wxPoint(r2.x + border - radius, r1.y - border)
center = wxPoint(start.x, start.y + radius)
add_line_arc(start, center)
start = wxPoint(start.x + radius, d1.y + border - radius)
center = wxPoint(start.x - radius, start.y)
add_line_arc(start, center)
start = wxPoint(r1.x - border + radius, start.y + radius)
center = wxPoint(start.x, start.y - radius)
add_line_arc(start, center)
start = wxPoint(start.x - radius, r1.y - border + radius)
center = wxPoint(start.x + radius, start.y)
add_line_arc(start, center)

pcbnew.Refresh()

Remove All Lines

You may want start with a fresh slate.

import pcbnew

board = pcbnew.GetBoard()
for dr in board.GetDrawings():
   board.Delete(dr)

pcbnew.Refresh()

Conclusion

KiCad 6 provides adequate scripting capability for designing pcb’s of moderate complexity.

KiCad projects that use Python scripts:

Optical Keyboard: Circuit Design

2022-08-17T10:16:45+00:00

This guide will walk you through some concepts that will help you design a basic optical keyboard PCB. No special knowledge is assumed beyond engineering basics. The circuits used here are rudimentary and they will provide performance comparable to a mechanical keyboard. Low latency specialized circuits are not covered in this guide.

You can think of optical switches as apertures through which infra-red (IR) light (from LED) is allowed to pass through and shine on a phototransistor (PT). When switch is pressed the aperture window closes and stops the light from being irradiated on PT. PT generates current in response to light. A photodiode can also be used in place of phototransistor, but we will limit the discussion to PT. A PT is a combination of photodiode and another junction diode, making it a NPN transistor whose base is exposed to light. The current generated by PT has a near linear relationship with the amount of light shone on the base.

A PT is an analog device that produces current. This current needs to be converted to voltage at appropriate digital TTL levels before the ‘state’ of the switch (on/off) can be read by the GPIO (general purpose input-output) pin of a microcontroller. We use a passive device like a resistor to convert current to voltage. On the other hand, if you were to use a photodiode (which produces very small current) an active device like an OpAmp is needed to convert current to voltage (transimpedence).

We are interested in only two states (on/off) for digital operation. We are not interested in partial keypresses for instance (analog operation). So we drive the PT between saturation (on) and cutoff (off) states.

Circuit

There are two ways you can measure voltage drop across PT. The circuit shown in Figure (A) is a common-emitter amplifier, with IR LED shown on left and PT on the right. Light input at the base causes the output (Vout) to decrease from high to low. If you were to connect Vout to the input pin of MCU it would read LOW to HIGH when switch is depressed. The circuit shown in Figure (B) is a common-collector amplifier with an output (Vout) increasing from low to high in response to light input. In this case MCU pin will read HIGH to LOW. For these circuits to operate in the switching mode, Vcc < RL × Ic, where Ic is the maximum anticipated current and Vcc is the supply voltage.

What are the values of R and RL?

Majority of current is consumed by the IR LED. First we have to determine how much current is available for each IR LED, and then we can use Ohm’s law to calculate R. As a USB ‘device’ a keyboard is allocated 500mA current. We can budget up to 300 mA for optical switches for instance, and use the rest for microcontroller and backlight. We can allocate the current budget to each IR LED based on the matrix we choose. This will become clear later. RL is chosen by trial-and-error such that multimeter reads TTL level voltage when switch is on/off. Value of RL depends on the brand/type of PT and amount of IR light falling on PT. Here are some values for Everlight IR12-21C/TR8 and PT12-21B/TR8 combo. Please do your own experiment to fine tune RL. You can also use 5V source directly from USB instead of 3V3 for powering IR LED.

For 3.3v:

R	I	RL	Ic
540	4.2 mA	4k	0.83 mA
1.5k	1.4 mA	27k	0.18 mA
2.2k	1.0 mA	45k	0.1 mA

Voltage across R is ~2.14V
I = 2.14/R, and Ic ~ 3.3/RL
R and RL are in ohms

Rise and Fall Time

Recall that a PT is also a transistor. Transistor provides current amplification but also brings its peculiarities. The time needed for PT to reach saturation and thereby rise the voltage (say from 0V to 3V) is called ‘rise’ time. More specifically, rise time is the time needed for PT to rise from 10% of LOW value to 90% of HIGH value. Similary ‘fall’ time is defined for the reverse situation. In addition, there is ‘storage’ time which is the time the transistor stays on even after the base current (in this case light incident on the base) has been removed. Storage+fall time is slightly larger than rise time because transistor junction behaves like a capacitor. The charge stored in the base junctions must be removed before the transistor will turn off. The deeper the saturation of transistor the longer the turn off time. Rise, storage and fall time of PT directly impacts the latency of a keyboard.

How quickly does a PT rise and fall? Here are some illustrative examples for a PT driven to saturation. The circuit is the common-emitter amplifier from above (A). Vcc is set at 3.3V. PT used is Everlight PT12-21B/TR8 and IR LED is IR12-21C/TR8. Rise and Fall times for various R and RL values are given below. The oscilloscope screens represent the items in the table. Green line represent the voltage drop across PT and yellow line is the voltage drop across IR LED. us/div number represents millisec per division (horizontal). Current across PT is not calculated since it is a much smaller value.

R	IR LED Current	RL	Rise Time	Fall+Storage Time
1k ohm	2.3 mA	30k ohm	~250 us	~300 us
300 ohm	7.5 mA	4.5k ohm	~100 us	~100 us
100 ohm	20.2 mA	1.8k ohm	~20 us	~20 us

In the above pictures voltage values are inverted. ‘Rise’ is when yellow line goes from high to low, and vice versa. Rise and fall times are approximations eye-balled from oscilloscope plots.

It may appear execessive that at least 20mA current is needed to achieve rise time of 20us. But with minor modifications to the circuit it is possible to achieve 1us rise/fall time expending only a few mA current. Using photodiodes and OpAmps is not necessary.

Optical Matrix

The total number of switches in a full-sized keyboard far exceed the number of digital pins available in a microcontroller for reading TTL voltage levels. We can solve this problem two ways: 1) Use a matrix arrangement where a single GPIO pin is connected to multiple PTs but only one of the PTs is ‘active’ at any given time, 2) Use a separate device like a multiplexer or shift register to read multiple PT voltages from a single GPIO pin. In the former case only a subset of IR LEDs are switched on at any given time (‘scanning’ the matrix). In the latter case all IR LEDs can be switched on and switch states can all be read at once. By now you may have already have some ideas about the matrix you want to design. Following section covers only basic information.

Optical matrix is not much different from matrix used for mechanical switches. You either select a column and read rows one by one, or vice versa.

Select Column and Read Rows

In this arrangement we switch on all IR LEDs in a give column and read PT values across rows. Pseudocode would look like this:

initialize GPIO pins

forever do:
    for column in all_columns do:
        select column  /* switch on power to column */
        delay          /* wait for rise time */
        for row in all_rows do:
            read row   /* read state of switch */
        unselect column /* switch off power to column */
        delay          /* wait for storage and fall time */

    compare matrix_state with matrix_state_from_previous_scan
    if above comparison returs true: 
        copy matrix_state to matrix_state_from_previous_scan
        return matrix_state
        

To power IR LEDs in a column you can use a GPIO pin directly (set as OUTPUT). ARM based microcontrollers like RP2040 or STM32F4 can handle 20 mA current per pin (for a maximum of ~40 mA across all pins). If you have 5 columns you can supply 3.5 mA per IR LED (leaving 0.5 mA for PT).

Reading time is usually negligible compared to PT rise/fall time. A full matrix scan will take approximately (rise_time + fall time) x number_of_columns.

Select Row and Read Columns

In this arrangement we select a row and read column pins one by one. A full matrix scan will take (rise_time + fall_time) x number_of_rows. This is my preferred arrangement since we can achieve higher scan rates. Rows can be powered using a N-Mosfet acting as a low-side switch connected to a GPIO pin at the gate. We can supply higher power to IR LED since we are not limited by GPIO pin.

Note: To minimize power losses IR LEDs could be connected in series when possible. Modify the above schematic accordingly for your use-case. Voltage drop across IR LED (Vf) is typically 1.2V-1.3V. Using a 5V supply it is possible to connect 3 IR LEDs in series and still have headroom for regulation. LED forward voltage drop has inverse relationship with temperature. As LEDs heat up the forward voltage reduces resulting in more current. This causes further increase in temperature and could lead to thermal runaway. It is good to keep 20%-30% voltage headroom across resistor for proper regulation.

Optimization

One easy way you can increase the performance is by splitting the matrix into two. We can scan rows from each matrix alternately. This way when one matrix is waiting in ‘rise’ time, the other is waiting in ‘fall’ time. But storage time has to be accounted for each row separately. Latency is decreased by the same amount as rise time.

Using RP2040 (which has 30 GPIO pins) in a keyboard with 72 switches we can use 2 4x9 matrices, and we need 26 GPIO pins. Each row has 9 IR LEDs and each can be supplied with at least 20mA.

FS (full speed) USB supports 1 ms polling (1 kHz) while HS (high speed) USB supports 125us polling (8 kHz). Even though phototransistors are inherently slow it is possible to achieve ~8 kHz scan rate using PT without additional circuitry, while photodiodes in combination with OpAmps can generate square waves upto 100 kHz. Hopefully, this writeup kindled some curiousity in you about the workings of optical keyboards.

Optical Keyboards

Questions?

Optical Future

girish

Vim Plugin using Vim9 Script

Directory Structure

Language Features

Lambda Expressions

Meta Tables

Options

Strings

Debug

Disassemble

Asynchronous Execution

Performance Measurement and Timing

Expose APIs to Other Plugins

Autocompletion for Vim9 Script

Keyboard: How Quickly Can You Press a Key

Setup

Fast Key Press

Average Key Press

Lazy Key Press

Average Key Release

Note

UPDATED Jan 21, 2023

Conclusion

KiCad 6 Python Scripting: Place Footprints, Create Tracks, Curved Tracks, Vias, and Edge Cut Lines

Contents

Introduction

How to Run Python Script

KiCad Coordinate System

Footprints

Place Footprint

Tracks

Straight Track

Curved Track

Create Via

Remove All Tracks and Vias

Edge Cuts

Draw Line

Draw Arc

Remove All Lines

Conclusion

Optical Keyboard: Circuit Design

Circuit

What are the values of R and RL?

Rise and Fall Time

Optical Matrix

Select Column and Read Rows

Select Row and Read Columns

Optimization

Optical Keyboards

Questions?