Documentation - lechef circuit API and exercise
Getting started
There are two ways to get lechef: git clone or zip download. If yout have git
installed, getting lechef source
code is simple as going to command line, change directory to
where you want the code to be downloaded (git will, by default, make a subdirectory called lechef
), and cloning
the lechef repository by typing the command
git clone https://github.com/vkaravir/lechef.git
Now you have the lechef code in the lechef
directory.
If you don't have git
installed, you can download a ZIP file
of the code and unzip it.
Whichever way you got the code, the important directories are build
where the lechef JavaScript and CSS files are,
and libs
which contains the required JS libraries. lechef does depend on jQuery, jQuery-UI, and Snap.svg.
To get started, read on, or, check the examples in the (awesomely named) examples
directory. They do look like
crap, but that's to keep the code simple and clean (and not because I'm lazy or anything :) ).
Circuit design exercise
The circuit design exercise requires the learner to build a logic circuit matching the assignment description. Typically, this would be the truth table or Boolen expression describing the circuit. While this type of assignment is more difficult to the learner than the simulation exercise, the configuration of this type is quite straightforward. The exercise is initialized with the CircuitExercise
constructor. Here's the initialization of an exercise:
var exer = new CircuitExercise({element: $("#design-example"),
input: ["x", "y"],
output: "g",
grading: [{input: {x: true, y: false}, output: true},
{input: {x: false, y: true}, output: false},
{input: {x: true, y: true}, output: false},
{input: {x: false, y: false}, output: false}],
components: ["and", "not", "or", "eqv"],
addSubmit: false });
The first thing to note is that lechef doesn't generate any kind of assignment description. That's your job to do when you include an exercise into any HTML page.
Let's go through the options, one by one.
element
- The DOM element where the logic circuit and the buttons to create components should be added.input
- An array of names (so, strings) of the inputs of the circuit.output
- The name of the output of the circuit, again, a string.components
- An array of strings for the components to be available for the student. Defaults to["and", "not", "or"]
. The available components areand
,nand
,or
,nor
,xor
,eqv
, andnot
.addSubmit
- Whether or not to add a Submit button to the toolbar. Defaults totrue
.grading
- An array of input - output values that the constructed circuit should match. Essentially, this is the truth table of the circuit. Each item in the array should have propertiesinput
andoutput
. Theinput
property should be an object with properties for each of the input names and values for the values of the inputs. Theoutput
property should be the expected output value with the inputs. The values should all be booleans, so eithertrue
orfalse
.lang
- The language used, as an ISO language code. Defaults toen
for English. The other supported language is Finnish (fi
). Can you tell I'm Finnish :)
Circuit Simulation exercise
In the circuit simulation exercise, the learner is given a logic circuit and the input values are fixed and given. The exercise requires the learner to set the values of all the inputs and outputs of the components in the circuit to the correct values. This is done by toggling the values with mouse clicks.
Depending on the circuit, the exercise can be a bit cumbersome to create, since it requires creating the circuit by coding. A circuit is initialized with the LogicCircuit
constructor. This instance is used to build the circuit (using the API described below). The exercise itself is initialized with the CircuitSimulationExercise
constructor. Here's the initialization of a exercise:
var circuit = new LogicCircuit({element: $("#first-example")});
var andComp = circuit.andComponent({left: 250, top: 60});
var in1 = circuit.inputComponent("x", {left: 50, top: 10});
var in2 = circuit.inputComponent("y", {left: 50, top: 110});
var out = circuit.outputComponent("f", {left: 400, top: 65});
andComp.inputComponent(0, in1);
andComp.inputComponent(1, in2);
out.inputComponent(0, andComp);
var simulation = new CircuitSimulationExercise(circuit, {input: {x: true, y: false}});
The options of the CircuitSimulationExercise
constructor are:
input
- The values for the input components which the learner should simulate the circuit with. This should be an object with properties matching the labels of the input components and the values booleans.lang
- The language used, as an ISO language code. Defaults toen
for English. The other supported language is Finnish (fi
).
The API
At the heart of the API is the LogicCircuit
type. It has functions to add the supported components to the circuit, such as .andComponent
for adding an AND gate. The objects returned by these functions are then connected with their .inputComponent
function. All the functions crucial for specifying the circuit for a circuit simulation exercise are briefly described below.
LogicCircuit(options)
Initializes a new lechef logic circuit. The only options supported :
element
- The DOM element where the logic circuit should be added.
logicCircuit.inputComponent(label)
logicCircuit.outputComponent(label)
These two functions create an input and output component (guess which one is which). They both take the label
used
for the component. This really should be a one-character label in order to properly fit inside the component.
logicCircuit.andComponent()
logicCircuit.nandComponent()
logicCircuit.orComponent()
logicCircuit.norComponent()
logicCircuit.xorComponent()
logicCircuit.eqvComponent()
logicCircuit.notComponent()
The above functions create the components that you can most probably deduce from the name of the component.
component.inputComponent(inputNbr, component)
All the functions to create a component return an instance of the component. All the objects have the inputComponent
function to specify where the input for the component is coming from. The inputNbr
is the position of the input
(zero-based, top-to-bottom) and the component
is another component object, the output of which will be the input
for this component. In the example above, the andComp
gets as its input 0 the input component with label x
and as input 1 the input component with label y
.
More Examples?
I'm working on creating a more versatile set of examples.. But won't make any promises on when they might arrive :)
Want to Use lechef For "Something Else"?
Using the lechef circuit API, you can create logic circuit visualizations. Also, the editor used in the design exercises could
be used to create circuits in other contexts as well. Check the src/js/circuits.js
and
src/js/circuit-editor.js
for the source code of those parts.