Specifying a Keyguard for a Free-form or Hybrid AAC App

Next Level Keyguards

“Next Level” means that you’re going beyond the options in the Customizer pane of OpenSCAD and giving the designer explicit instructions by entering instructions into the “openings_and_additions.txt” file.

You can edit the openings_and_additions.txt file with any simple text editor. Avoid complex ones like Microsoft Word.

When you look at the contents of the openings_and_additions.txt file, you’ll see this (click on the image to expand it):

If you look closely, you’ll see references to three “things” (actually, data structures):

screen_openings – removes or adds plastic from/to the screen region of the keyguard
case_openings– removes or adds plastic from/to the case region of the keyguard
case_additions – adds plastic to the perimeter of your keyguard to fill in the cuts in the case opening.

When creating a hybrid keyguard, you do most of your work in the Customizer pane of OpenSCAD and make “just a few” entries in one or more openings_and_additions.txt file. A free-form keyguard will require that you do almost all of your work in the openings_and_additions.txt file.

Note: You can do many of the same things by putting instructions into either the screen_openings data or the case_openings data – but the case openings entries are sensitive to an unbalanced case opening while screen opening entries are not. So, if you need openings or additions to be attached to screen elements, put them in screen_openings. For example, the raised landmarks around the outside of the screen in the LAMP Words for Life – VI keyguard need to go in the screen_openings instructions even though they “legally” fall outside the screen region because they are critical to locating the screen elements.

If your keyguard is going into a non-rectangular case opening, you might want to consider adding additional plastic to the outside edge of your keyguard.

We’ll begin by describing the basics of creating openings and additions in a hybrid keyguard—meaning: mostly grid-based. Then, go here to explore the world of free-form keyguards: virtual keyboards, keyguards for PC keyboards, and very creative AAC apps.

Note that we have separate designers for creating Chromebook Keyguards and Keyguards for iPad Keyboards.

Screen Openings or Case Openings?

You have two options for indicating where an opening or other feature should be placed on your keyguard. If you’re placing a feature within the area of the screen, the screen_openings data structure within the openings_and_additions.txt file will probably be the easiest way to go. If you’re placing a feature outside of the screen area but still within the case opening, the case_openings data structure will probably be the easiest way to go. This image shows the relationship between the screen region and the case opening region:

As you can see, the screen sits within the case opening, so it’s possible to specify features in the case_openings data structure that would be placed within the screen region of the keyguard. However, that will probably be a less effective approach—especially if the screen doesn’t sit in the middle of the case opening. This can be by design, or it can just be a poorly made case.

When placing an opening or other feature in your keyguard, you will need to specify the x- and y-coordinates for that opening.

By default, the instructions that you put in the screen_openings data structure use pixels as their units, and the x- and y-coordinates are measured relative to the upper left-hand corner of the screen:

This works well if you’re using a screenshot and a graphic editor like Microsoft Paint as the basis for your measurements, but you can take a different approach if you are using another editor or simply measuring distances with a metric ruler. To change your approach, you change the options in the Free-form and Hybrid Keyguard Openings section:

Specifically, if you want to use a metric ruler to take your measurements, set the “unit of measure for screen” to “mm.” If you want to take your measurements from the lower left-hand corner of the screen, set the “starting corner for screen measurements” to “lower left.”

Instructions that you put in the case_openings and case_additions data structures use millimeters as their units. The x and y coordinates are measured relative to the lower left-hand corner of the case opening and the lower left corner of the tablet when placed in landscape orientation with the home button on the right and the camera on the left:

Specifying the Location, Size, and Shape of the Openings

Once you know which region your openings or additions fall into, you can start collecting measurements for those features.

Basic Shapes

You can take inspiration from the shape of the item in the app or go with a shape that provides the best access to the screen. Experiment to find what works best.

You have six basic shapes to choose from:

They are a rectangle (represented by the letter “r”), a rounded rectangle (represented by the letters “rr”), and a circle (represented by the letter “c”).

We couldn’t find an official name for the last shape, so we chose the first thing that came to mind – a hot dog (noted by the letters “hd”). Basically, it’s a rectangle with a semicircle at either end of the long dimension.

The red circles represent the shape’s anchor point. To place the opening, you’ll need to tell the designer the location’s x- and y-coordinates. The “cr” and “crr” shapes are anchored at their center rather than their lower left-hand corner. These shapes can be particularly useful if you want to design a keyguard where you can easily experiment with the height and width of the opening without changing the relative location of the opening. This is similar to how openings behave when you specify them in the Customizer.

Make a record of your measurements and decisions. For each object, record the following information:

ID number,
x-coordinate,
y-coordinate,
width,
height (this column is used for the diameter of a circle),
shape (r = rectangle, rr = rounded rectangle (as well as cr and crr), c = circle, hd = hot dog),
top slope, bottom slope, left slope, and right slope are measured in degrees and determine whether each side of a rectangular opening will be sloped (top slope controls the entire perimeter slope of a circular opening),
corner radius controls the size of the rounded corners of rounded rectangles,
other – you can control the depth of the cut by putting a value in the “other” column (this value will always be assumed to be in millimeters regardless of how the “unit of measure for screen” option is set)

Here are examples of values in the “other” column that affect the depth of a cut:


<no value> cuts all the way through	1

3	4 (with a 4 mm-thick keyguard)

These same columns may be used slightly differently for some of the special shapes described below.

The ID number is ignored by the designer and is strictly for your benefit in tying an instruction in the .txt file with a real world element – if things aren’t falling into place. You can put text in this column if that is more meaningful for you but you must put that text inside of double quotes (e.g., “Vocab”).

There is a special value that you can put in this column that will help you if you’re having trouble positioning a cut. That value is “#”. If you add this value to one or more instructions in the openings_and_additions.txt file. The associated cut/opening will appear in red:


instruction with “#” in the ID column

displaying the location and shape of the cut	how this looks after the Render step

While the example above is associated with an instruction in the case_openings region of the file, the same technique can be applied in any of the three sections.

The x and y coordinates for rectangles and rounded rectangles represent the lower left corner of the shape. The x and y coordinates for circles and hot dogs represent the center point of the shape.

You specify only the width of a circle, while you specify both the height and width of the other three shapes. Rounded rectangles will require that you additionally specify the corner radius.

You’ll specify some additional information for each opening, but it’s best to decide their value in real-time when you can observe what the various openings look like in your keyguard in OpenSCAD. Those pieces of information are the slope of the walls around the opening and the radius of the corners of the rounded rectangles. You have complete control, and each opening can be specified independently of every other opening.

Getting even fancier with arcs, text, and graphics:

When to use an “Outside Arc” Shape

There may be instances where you want to cut a shape in your keyguard that results in a sharp corner. In the example below, you are creating two joined cutouts:

In another instance, your cut may extend beyond the outer edge of the keyguard:

In both examples, you can soften the edges of these sharp corners by cutting an outer arc.

There are four types of outer arcs depending on how the cut should be rotated:

The second example (where the cut extended beyond the right edge of the case) can be “softened” by inserting an oa1-shaped cut on the bottom corner and an oa2-shaped cut on the top corner. The result looks like this:

To position an outer arc cut, you set the x and y location based on the tip of the corner that you want to soften and the corner radius (i.e., the amount of softening to perform):

If the edges connected by the arc are sloped, you can specify the same slope for the arc (change the value of “top slope” from 90 to the slope you want). Below, the outer arcs connect a top message bar with a 60-degree slope to a custom rounded rectangle cut with a 60-degree slope. If the outer arcs on these resultant corners have a standard 90-degree slope, the keyguard will, strangely, look like this:

By setting the “top slope” value of the two outer arcs to a matching 60-degree value, the corners will take on a more natural look like this:

Engraved/Embossed Text

Note that you can engrave and emboss a single line of text on your keyguard using functionality available in the Customizer pane, but if you want more precise control over text size and location or if you want to put more than one instance of text on your keyguard, then you have that ability by inserting additional instructions into the openings_and_additions.txt file.

You can specify text to be engraved or embossed on your keyguard. One example would be to engrave the name of the student on the region of the keyguard that would otherwise cover the upper command bar:

This engraved text was created by inserting this line in screen_openings data structure:

[ 1, 67, 20, 0, 6,”ttext”, 0, 0, 90, 90, -2, “Rodrigo”]

67 and 20 are the x and y coordinates in millimeters from the upper left of the screen. 6 is the height of the text in millimeters. “ttext” is the shape type. The 0 in the “top slope” column means that the text value should be written horizontally. The value of 0 in “bottom slope” determines the font style” (0=normal, 1=bold, 2=italic, 3=bold italic). Any value from 0 to 360 (including negative values) can go in this slot.

The -2 value before “Rodrigo” tells the designer that this text is to be engraved at a depth of 2 mm. Values greater than zero produce embossed text (for top text only). Values smaller than zero produce engraved text. The the larger the value, the taller the embossed text will be. The more negative the number the deeper the engraved text will be.


Engraved Text	Embossed Text (top text only)

The last value, “Rodrigo” is the text that will be engraved and occupies the column called “other”.

The x and y values represent the specified horizontal and vertical alignment settings of the text – including any descending characters when the text is displayed horizontally and the opposite when the text is displayed vertically. You specify the horizontal alignment in the “left slope” column:

left = 1,
center = 2,
right = 3

You specify the vertical alignment in the “right slope” column:

bottom = 1,
baseline = 2,
center = 3,
top = 4

These values are illustrated below.


horizontal alignment	vertical alignment

The top slope value determines how the text should be rotated:

You can place text (and any cut) outside of the area of the screen by using x and/or y values that are negative or larger than the size of the screen.

You can more conveniently make cuts and engrave text outside of the screen area by putting the instructions in the “case_openings.” data structure. It’s more convenient because you can use units that are more natural to this region (i.e., millimeters) and you can take your measurements from a more natural starting place – the lower-left corner of the case opening. Note that, as its name implies, the program will ignore the data in “case_openings” if you tell it that you’re not using a case.

This video demonstrates how to add a serial number to the underside of your keyguard:

Engraved and Embossed Graphics

OpenSCAD supports adding graphics to a design so why not use it to provide even more personalization for your keyguard!

There are several websites for obtaining free SVG graphics files. Free SVG Designs and Free SVG are just two of them. You’re looking for graphics that are just black and white images. If you find something you really like but it’s not in SVG format, you might be able to convert it to SVG by using these tools.

For example, let’s assume that you love butterflies. A quick search of these websites will show you several options. I chose one that looks like this:

You can engrave or emboss this image on your keyguard:

Of course, you’ll need an appropriately sized area of plastic on your keyguard to place the image. In the keyguards above, I set aside the central part of the grid (by covering that cell) for the butterfly. You could also put the image in the space between the screen and the opening in the case.

There are some real limitations, however, that are simply the result of creating your keyguard with a 3D printer. The nozzle that extrudes the melted plastic has an opening that is normally 0.4 millimeters in diameter. So you can’t create a feature of your graphic that is smaller than that. For example, I found this really nice SVG of a lion:

I wanted to put it on a keyguard but it needed to fit in a space about 15 mm wide and 10 mm high. Here’s what it looked like embossed and engraved on a piece of plastic:

As you can see, the embossed lion’s tail is just two dots and all the impressive elements of it’s head are unrecognizable. The engraved lion results were “better”. Still not terribly impressive but at least you might “guess” that it’s a lion.

You may find that, for small shapes with fine details, engraving works better than embossing. In either case, you can’t trust the image that you see in OpenSCAD because it doesn’t know the limitations of your printer.

Instead, take a look in your slicer to see what the printer will actually do.

How do you add graphics to your keyguard?

You tell keyguard.scad to add graphics to your keyguard by inserting a line into the screen_openings or case_openings data structures. That line will specify the x and y locations for the center of the image, the width and height of the final graphic, how you’d like to rotate the image, the name of the file that contains the SVG graphic, and whether the graphic should be engraved or embossed.

Start by specifying the x and y location for the center of the graphic (shown with a red dot below):

Note that the center of the SVG may be off a little but that’s a good place to start. You may need to alter the x and y values a little to get what you want.

Choose height and width values based on the size of the open area of your keyguard where you want to place the graphic. You can choose any values for height and width. The values you choose may not preserve the aspect ratio of the original image. [If you want to see the the aspect ratio of the original image, you can open the SVG file in your web browser and then save it as a picture. The properties of the picture file will indicate the number of horizontal and vertical pixels associated with the image.]

Put “svg” (in double quotes) in the “shape” column.

If you want to change the orientation of the graphic, place that value in the “top slope” column. The picture below shows four different orientations and the values that would cause them:

You aren’t limited to just these four values, you can insert any number between 0 and 359 or -359.

If you want to engrave your graphic, put a value smaller than or equal to 0, in the “corner radius” column. The smaller the number, the deeper the engraving. To emboss your graphic, put a value larger than 0 in that column. The larger the value the taller the embossing.

Finally, you have to tell keyguard.scad the name of the file that contains the SVG graphic that you want to put on the keyguard. Be sure to place the SVG file in the same folder as the keyguard.scad program and then put that name (in double quotes) in the “other” column.

Save the .txt file and you should see your graphic appear in the OpenSCAD program. Note that SVG graphics can be made up of lots of lines and curves, so expect that it will take a little longer for your keyguard to Render.

Adding Features for Individuals with Visual Impairments

The designer provides a few raised features to support people who are visually impaired. These features can only be added to the top surface of the keyguard.

You can add bumps along with horizontal, vertical, angled, and arc-shaped ridges.

bump = a hemisphere on the top surface of the keyguard,
hridge = a wall that runs horizontally on the surface of the keyguard
vridge = a wall that runs vertically on the surface of the keyguard
ridge = a wall that runs at an arbitrary angle
aridge1-4 = add small arc shaped walls. The number following “aridge” corresponds to the quadrant associated with the arc – similar to outer arcs.

You describe the bump by specifying its center and width. The vertical and horizontal ridges are specified using an arbitrary x and y location followed by the height or width of the ridge, respectively. The “ridge” shape uses the “width” field for its length and “left slope” for its angle. You use top slope for the height of the ridge and bottom slope for the thickness of the ridge. You can add ridges around merged cells by combining horizontal, vertical, and arc ridges. More on that here.

To put a ridge around one or more openings, you can use the “add a ridge around these cells” option in the “Grid Layout” section in the keyguard.scad user interface.

Note: The case_additions and case_openings data structures are ignored by the designer if your tablet isn’t going into a case. You can still to put cuts or engraved text outside of the screen area by putting entries in the screen_openings data structure and using negative measurements. You may also have to work with measurements in pixels. Fortunately, you’ll be able to see all your instructions rendered in OpenSCAD and you can adjust your numbers until your changes are in just the right place.

Using Variables in the openings_and_additions.txt File

In addition to describing what kinds of cuts and additions you can make to your keyguard, the openings_and_additions.txt file includes a set of “variables” that you can use in your instructions. Here are some of the variables that you can use in your instructions:

These variables make it very easy to locate cuts and specify their size. Let’s say that you want to put a cut in the upper command bar to provide access to a command in that bar.

“ucbb” is the location of the bottom of the upper command bar
“ucbh” is the height of the upper command bar
“swm” is the width of the screen

So the following instruction puts a 10 mm cut at the right end of the upper command bar. Best of all, this works for any app that has an upper command bar!

// ID,      x,    y,  width, height,  shape,     ...                           
[   1, swm-10, ucbb,     10,   ucbh,    "r",     ...                    ],

Remember, if you’re going to be using measurements in millimeters in the screen_openings data structure, be sure to set “units of measure for screen” to “mm” in the “Free-form and Hybrid Keyguard Openings” section of the Customizer.

Example – the Lamp Words for Life – VI Keyguard

This page will take you through using the .txt files – and especially the variables they expose for you – to create the landmarks around the periphery of a LWFL-VI keyguard. Besides making the measurements easier for you, they make it possible to (almost) instantly create a matching keyguard for other tablets!

With all that in mind…

When you’ve gathered initial values described above for each opening, you should:

Open “keyguard.scad” in OpenSCAD and “openings_and_additions.txt ” in a text editor (like Notepad++).
Choose appropriate values for each of the customization options in OpenSCAD. Note that you won’t see any openings in the app region of the keyguard yet – those come next.
Using the text editor, create a row of data for every opening you want in the keyguard and update the ID number. You still won’t see any openings in the keyguard until you change the width and height values to something greater than zero.
Start to change numbers in openings_and_additions.txt files one opening (i.e., one row of data) at a time.
Save “openings_and_additions.txt” but don’t close the text editor. The image of the keyguard in OpenSCAD will update almost immediately to show the change that you made.
When you’re happy with the data you entered, move on to the next opening. If things don’t look as you expected, check the options you set in the Free-form and Hybrid Keyguard Openings category. The problem could be as simple as you made your measurements in millimeters and the option is set to pixels – or vice versa.
Set the radius for the corners of rounded rectangles. A value of 10% of the smallest dimension of the shape is a good rule of thumb. For example, if the shape is 15 mm by 20 mm, start with a corner radius of 1.5 mm; or if the shape is 200 pixels by 100 pixels, start with a corner radius of 10 pixels.
Repeat the process with the remaining openings.
This may be a good time to test the location, size, and shape of the openings against the actual app running on the target tablet or against the screenshot. The former method is the most accurate but the later is quicker and will identify obvious problems.
When you’re satisfied with the location, size, and shape of the openings, you can explore the impact of sloping the sides of each opening. Sometimes the objects will simply be too close together to have anything other than sides with a 90 degree slope. You can independently set the slope of each side of a rectangle. The remaining shapes use a single slope value for all edges of the shape.
When everything is laid out nicely – or at least as nice as the app will allow – save your keyguard design as an STL file and print it.

Editing the openings_and_additions.txt File

This video describes the steps needed to create a hybrid keyguard.

Note that the video talks about several different txt files but those have now been consolidated into a single txt file.

Adding Plastic to the Outside Edge of Your Keyguard

Some case openings are more complex than a simple rounded rectangle. If you want your keyguard to closely match the shape of such a case opening then you’ll need to give the designer that information by putting instructions in the openings_and_additions.txt file. You can learn how to do that here.