pcb-rnd knowledge pool

 

Index: scripting pcb-rnd

Iscript by Tibor 'Igor2' Palinkas on 2019-05-19

Tags: index, user, guide, howto, tutorial, intro, introduction, scripting, script, fungw, action

node source

 

 

Abstract: Enumerate various ways pcb-rnd can be scripted, allowing the user to extend the functionality of pcb-rnd or automate repetitive tasks or integrated pcb-rnd as a converter/generator in a toolchain or build system.

 

Summary

class name domspec turcomp
fungw stored user scripts no yes
interactive one-liner no yes
interactive, multi-line (live scripting) no yes
action interactive one-liner no no
from the command line no no
from the menu file no no
output
control
CAM yes no
XY template yes no
data access
& search
DRC
query ,
DRC
yes no
data creation ddraft yes no

Details

fungw: stored user scripts

Fungw allows the user to use one of 10+ different popular scripting languages to script pcb-rnd. Three of these are always available without any extra step: fawk, fpascal and fbasic. Other languages, such as python, lua, javascript, ruby, lisp variants, etc., require extra installation steps.

Stored user scripts are written in the user's preferred scripting language (e.g. awk, lua, python, etc.) and is loaded by pcb-rnd from the disk, from (a) script file(s).

Stored user scripts can extend pcb-rnd by defining new actions, menu entries, exporters.

The most common use for user scripting is sharing and downloading user scripts through edakrill, which allows users to flexibly extend pcb-rnd features without having to touch the C code.

For more details, please read the user manual .

fungw: one-liners on the command line

Fungw allows the user to use one of 10+ different popular scripting languages to script pcb-rnd. It requires extra installation steps.

The easiest way to execute a script is using the script engine's name as action, e.g.:


	awk('for(n = 0; n != 4; n++) message("counting " n)')
	python('message("sum: ", (4351+771))')
	lua('message("conv: ", (1500/2.54))')

This will work in any context where pcb-rnd actions are accepted, e.g. in the GUI command line (press colon) or --gui batch mode.

An alternative is to execute the script engine's name as action, but without arguments. To quit from the new script mode, type /exit. This will switch the command interpreter to that language. The prompt will change to reflect the current scripting language. For example:


	awk
	message("hello!")
	for(n = 0; n != 4; n++) message("counting " n)
	/exit

Note: this is still one-liner mode: each line is executed in a new script context, thus variables don't survive.

For more details, please read the user manual .

fungw: live scripting

Fungw allows the user to use one of 10+ different popular scripting languages to script pcb-rnd. It requires extra installation steps.

In live scripting the user edits a script in a dialog box within pcb-rnd. The dialog box has buttons for immediate testing of the script. This mode is typically used for developing a multiline script that will then be saved and used as stored user script

actions: one-liners

pcb-rnd offers a basic action scripting language with a rich collection of actions. Actions access most parts of the infrastructure - all menus and hotkeys are only executing actions.

The easiest way to invoke actions is to press the colon key on the GUI to get a command line where actions can be typed. Alternatively start pcb-rnd with argument --gui batch to get a CLI-only version that is waiting for actions on stdin. In GUI mode the --listen command line argument sets the GUI to still accept commands on stdin (but it will not be printing the prompt).

actions: automated, from the command line

pcb-rnd offers a basic action scripting language with a rich collection of actions. Actions access most parts of the infrastructure - all menus and hotkeys are only executing actions.

The typical way to run multiple actions in a non-interactive way from the command line:


echo '
 LoadFrom(Layout, "board.lht")
 UnSelect(All)
 query(select, "@.plated == 1")
 Export(png, "--dpi", 1200, "--as-shown")
' | pcb-rnd --gui batch

The above script loads board.lht, unselects all objects then selects any padstack that has plated hole or slot and exports the result in colored png (to make the selection visible).

actions: from the menu file

pcb-rnd offers a basic action scripting language with a rich collection of actions. Actions access most parts of the infrastructure - all menus and hotkeys are only executing actions.

In fact, the most important and common use of actions is from the menu file. All a menu item, a toolbar tool (and associated hotkeys) do is executing a series of actions. Thus simplest way to define a new functionality is to:

CAM: export jobs

The CAM export plugin offers a tiny, domain-specific language for configuring multiple export plugins to produce different exported files from different layer groups as part of a single CAM export job.

The language is a sequential list of simple instructions that select the export plugin and generate output files with the last selected plugin.

CAM scripts are easy to share. Rationale for the CAM system.

XY templates

The XY format is not really a format, just a generic idea of exporting part information, part including metadata and geometry (where to place a part in what orientation). As many different purposes there are, as many XY formats they need. Thus pcb-rnd's XY export plugin uses a XY template language to write the output file. This way the user can easily specify the file format without having to worry about how the data is extracted from the board.

query

pcb-rnd's query language is a small, declarative, domain specific language that uses logical expressions to describe complex searches on the board. In practice, for common searches it is rather easy to write the query scripts, see these examples. There is also a GUI aid, the advanced search dialog that provides a graphical way to build the query expression.

drc_query: scripting the DRC

The main DRC plugin is executing scripts written in the query language . DRC scripts can be exported and imported . User contributed DRC scripts are normally downloaded from edakrill but the pool has a few examples with detailed description that serve as a tutorial.

ddraft: 2d drafting

Drawing complex, predefined geometry with precise lengths and angles may be challenging with using only the grid. The ddraft plugin introduces an optional, domain specific mini-language for 2 dimensional drafting , similar to those found in command line of 2D mechanical CADs for decades. When used from the GUI, the command line has full integration with the mouse: selecting coordinates and objects will be intered automatically in the command.

Footnotes

domspec - domain specific

Domspec means "domain specific". Domain specific scripting means the scripting language and/or environment is designed to operate only on a narrow field of tasks. A typical example of a domain specific language is a configuration language: it is capable of describing a configuration but it can not be used to solve problems outside of that narrow domain. In return these languages are simple, compact and highly optimized for the given task.

Non-domain-specific scripting, or general purpose scripting provides enough access to the pcb-rnd infrastructure to be usable in any context.

Note: this is about the scope of the scripting in terms of access to infrastructure. This property is not to be confused with whether the language is Turing complete or not.

turcomp - Turing complete

A Turing complete language typically has conditional branches and states and is capable of solving a large class of computational problems. In practice this means the user can use variables, if-then branches, loops, functions.

A language that is not Turing complete typically offers much less flow control and/or no states (variables). In pcb-rnd context such language usually can be used only to describe a simple, ordered sequence of operations.

Note: this is about the syntax of the language. This property is not to be confused with whether the language is domain specific or not.