@logigator/logigator-simulation
TypeScript icon, indicating that this package has built-in type declarations

1.2.0 • Public • Published

Logigator - Simulation Code Base

Build Status Build Status

Multi-Threaded Simulator for Logic Circuits as Node.JS Native C++ Module, alternatively compilable to WebAssembly.

Getting Started

Prerequisites

You need to have node and npm installed to use this module. We recommend installing it via nvm:

Debian

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
nvm install lts/*

Furthermore, python2 is required for compiling:

apt install python2

Installation

Download the contents of the repository, open the command line in that directory and install it using npm install.

Linux / Unix

git clone 'http://github.com/logigator/logigator-simulation.git' && cd ./logigator-simulation && npm install

alternatively, you can install it using npm:

npm install @logigator/logigator-simulation

To compile to WASM, use this command:

npm run wasm-install

this will download emscripten and compile into webAssembly/dist/

Usage (Node.JS)

Import the module in your Node.JS Script:

const logicsim = require('./index').logicsim;

Alternatively, if you installed the package using npm, import it with:

const logicsim = require('@logigator/logigator-simulation').logicsim;

You can also import it using typescript:

import {BoardObject, logicsim} from "@logigator/logigator-simulation";

Functions

Function Description
logicsim.init(board); Creates a new Board. A sample board object can be found below.
logicsim.start(threads, ticks, ms); Runs the simulation until either the ticks were simulated or the simulation time was reached.
logicsim.stop(); Stops the simulation if running.
logicsim.getStatus(); Gets the current Status of a Board, like simulated ticks, current execution state or current simulation speed
logicsim.getLinks(); Gets states of all links
logicsim.getBoard(); Gets all components and links and their current state
logicsim.triggerInput(/*index of component*/, /*0 = set, 1 = pulse*/, /*array of states for input*/); Triggers an input element on a board
logicsim.destroy(); Destroys current board. This is required before initializing a new board.

Sample Board Object:

{
  "links": 4,
  "components": [
  	{
  		"type": 200,
  		"inputs": [
  		],
  		"outputs": [
  			0
  		]
  	},
  	{
  		"type": 4,
  		"inputs": [
  			0, 1
  		],
  		"outputs": [
  			2
  		]
  	},
  	{
  		"type": 2,
  		"inputs": [
  			0, 2
  		],
  		"outputs": [
  			3
  		]
  	}
  ]
}

Usage (WebAssembly)

Copy the .wasm and .js file to an appropriate location on your web server. Then, import the JS file and initialize WebAssembly:

<script src="/path/to/this/file/logigator-simulation.js"></script>
Module.onRuntimeInitialized = () => {
	console.log('Yay, it worked!');
};

To initialize a board, you can do as follows:

Module.initLinks(2); // Number of links on that board.
Module.initComponents(4); // Number of components on that board.
for (let i = 0; i < 4; i++) {
  // Allocate arrays for inputs and outputs in heap - further described below
  // ...
  
  Module.initComponent
  (
    i, // index of component to initialize
    1, // type id, determines which component to initialize - a list of all type ids can be found further below
    0x00000001, // pointer to array in heap holding indexes of the links going into the component - how to get an array into the heap is further documented down below
    0x00000010, // pointer to array in heap holding indexes of the links going out of the component
    1, // length of array located in 0x00000001
    1, // length of array located in 0x00000010
    0, // op1 - used for certain component types, ignored otherwise
    0 // op2 - used for certain component types, ignored otherwise
  );
  
  // release memory from allocated arrays to avoid memory leaks
  Module._free(0x00000001);
  Module._free(0x00000010);
}

Module.initBoard(); // finally, finish initialisation

To copy an array to heap, you can do:

function _arrayToHeap(typedArray) {
	const numBytes = typedArray.length * typedArray.BYTES_PER_ELEMENT;
	const ptr = Module._malloc(numBytes);
	const heapBytes = new Uint8Array(Module.HEAPU8.buffer, ptr, numBytes);
	heapBytes.set(new Uint8Array(typedArray.buffer));
	return ptr;
}

to retrieve data from heap (e.g. current state of links from board):

Module.HEAP8.slice(0x00000001 /*address of first byte*/, 0x00000010 /*address of last byte*/);

Functions

Function Description
Module.start(ticks, ms); Runs the simulation until either the ticks were simulated or the simulation time was reached.
Module.stop(); Stops the simulation if running. (Probably useless in webAssembly as active simulation locks current thread anyway.)
Module.getStatus(); Returns object with data for current state of the simulation
Module.getLinks(); Returns pointer with the states of all links (1 byte per element, Array length equals number of links on board)
Module.getComponents(); Return pointer with the states of all inputs and outputs of all components. Format: (component[0] inputs)(component[0] outputs)(component[1] inputs)(component[1] outputs)...(component[n] inputs)(component[n] outputs)
Module.triggerInput(/*index of component*/, /*0 = set, 1 = pulse*/, /*pointer to array of states for inputs*/); Triggers a user input
Module.destroy(); Destroys current board. This is required before initializing a new board.

Component Types

Type ID Name Inputs Outputs Ops
1 NOT 1 1 x
2 AND 2 - 2^32 1 x
3 OR 2 - 2^32 1 x
4 XOR 2 - 2^32 1 x
5 DELAY 1 1 x
6 CLOCK 1 1 [0] => Ticks between clock pulses
10 Half Adder 2 2 x
11 Full Adder 3 2 x
12 ROM 1 - 16 1 - 64 [0..n] => Data for ROM (1 Byte per element)
13 D Flip-Flop 2 2 x
14 JK Flip-Flop 3 2 x
15 SR Flip-Flop 3 2 x
16 Random Number Generator 1 1 - 2^32 x
17 RAM 1 - 16 1 - 64 x
18 Decoder 1 - 32 1 - 2^32 x
19 Encoder 1 - 2^32 1 - 32 x
20 Multiplexer 3 - (31 + 2^31) 1 [0] => select address size
21 Demultiplexer 2 - 32 2 - 2^31 x
200 User Input 0 1 - 2^32 x

License

This Project is licensed under the MIT License - see the LICENSE.md file for details

Readme

Keywords

none

Package Sidebar

Install

npm i @logigator/logigator-simulation

Weekly Downloads

1

Version

1.2.0

License

MIT

Unpacked Size

169 kB

Total Files

47

Last publish

Collaborators

  • xeinfallslos
  • liioooo