Issie (Interactive Schematic Simulator with Integrated Editor) is an application for digital circuit design and simulation. It is targeted at students and hobbyists that want to get a grasp of Digital Electronics concepts in a simple and fun way. Issie is designed to be beginner-friendly and guide the users toward their goals via clear error messages and visual clues. Issie is developed and actively used in teaching at Imperial College London.
For more technical info about the project, read on. This documentation is partly based on the excellent VisUAL2 documentation, given the similarity in the technology stack used.
For the Issie website go here.
The application is mostly written in F#, which gets transpiled to JavaScript via the Fable compiler. Electron is then used to convert the developed web-app to a cross-platform application. Electron provides access to platform-level APIs (such as access to the file system) which would not be available to vanilla browser web-apps.
Webpack 5 is the module bundler responsible for the JavaScript concatenation and automated building process: the electron-webpack build is automated using the pre-existing scripts under the scripts directory.
The drawing capabilities are provided (now) by a custom schemetic editor library implemented in F# and specialised for digital components.
The choice of F# as main programming language for the app has been dictated by a few factors:
If you just want to run the app go to the releases page and download and run the latest prebuilt binary for your platform (Windows or Macos). Issie will require in total about 200M of disk space.
Issie.exe application in the unzipped files.
sudo xattr -rd com.apple.quarantine /Applications/issie.appIssie installs and runs without making system changes - all of its code is inside the directory you download.
You can delete this and replace it by a later version of Issie. Each design sheet is stored in a similarly named file under the project directory.
The subdirectory backup there contains a large numbers of backup snapshots for design recovery.
These are not needed for Issie operation so you can delete them - or even the whole backup directory, if you wish.
Issie binaries will not run (in some cases) from a networked file location (found on many cluster machines).
If you have this problem navigate to the top-level directory containing the Issie binaries in a command window
and type issie.exe --no-sandbox. See https://github.com/tomcl/issie/issues/125 for details.
Once you open up Issie and are ready to go, feel free to open one of the Demo Projects from the start-up window. These are there to show you what a complete Issie project looks like and enable you to have fun with it without having to design and build it from scratch. Every time you reopen a demo project it will be reset to its initial state.
If you want to get started as a developer, follow these steps.
Download and install (if you already have these tools installed just check the version constraints).
npm package manager, so this does not need to be installed separately.Download & unzip the Issie repo, or clone it locally, or fork it on github and then clone it locally.
Check you have , .Net 7 (2024: .Net 8 will be OK too, I think), Node v18, VS 2022 (or latest VS Code + ionide or Rider) installed.
node -v shows Node version. dotnet --version shows Dotnet version.Navigate to the project root directory from the master branch (which contains this README) in a command-line interpreter, or start one from directory context menu.
Run build.cmd under Windows or build.sh under linux or macos. This will download and install all dependencies then launch the application in dev mode with HMR.
File -> reload pagenpm run dev. Run npm run debug for the debug mode (this is going to be a lot slower than dev).npm run dist.packet.json and therefore need to remake the lock file paket-lock.json use npm install.build killzombies will terminate orphan node and dotnet processes which occasionally happen using this build chain after unusual terminations (maybe no longer needed?)NB - in parallel with the above compilation, Issie code will always compile without errors (but not run) under dotnet, for example by building it from Visuak Studio. Compilation should be identical but when unsure why there is an error it is very helpful to build the current code under VS or VSC and get easier to find error messages. Similarly, VS or VSC can be used with confidence to refactor code, testing with compilation. Building under VS or VSC cannot work because the code depends on electron and Node APIs to work.
package-lock.json contains exact package versions and is downloaded from the repo. Normally you don't need to change this. The standard build above will run npm ci which checks and audits packages but does not change the lock file.package.json1) use npm install to recreate a lock file, which can be pushed to the repo.npm upgrade name or npm [-D] install name instead of editing package.json. npm ls name to find which of the required packages use it (usually upgrading or replacing them will remove the problem).A clean build will work equally well on macos, however things are more likely to go wrong if you have previously installed conflicting packages:
Legacy versions of dotnet - can if needed be removed as here:
curl -O https://raw.githubusercontent.com/dotnet/sdk/main/scripts/obtain/uninstall/dotnet-uninstall-pkgs.sh
chmod u+x dotnet-uninstall-pkgs.sh
sudo ./dotnet-uninstall-pkgs.shRoot permissions in dev files. For dev to work smoothly you need every configuration file to be installed under your own username, so you have r/w access. This will break if you ever find yourself using sudo to root install software, or if you have done this some time in the past. In that case you can temporarily get round issues by using sudo to run the development (or the generated app) with admin privileges. This is the wrong thing to do. Instead you should use
chown -R `whoami` dir
for each directory that might have the files with bad permissions. Typically your dev directory . and /usr/local.Uninstalling and reinstalling latest dotnet is helpful if dotnet has been installed wrong.
For Apple silicon Mac users, you should use the Arm64 version of .NET in order to get the best results. You can get it from the official Microsoft Website, using their installer. It is likely you will need to specify the location of the .NET installation to Visual Studio. This is under Visual Studion > Preferences > SDK Locations > .NET Core.
Although the dev chain is complex, it is now very smooth and identical for all platforms. Each of these steps can be performed as needed:
Dotnet SDK and Node installed. Dotnet SDK gives you F#.dotnet tool restore gets you the dev tools: Fable compiler, Fake build automation, paket dotnet package manager. (Node package management is via npm which comes with Node).dotnet paket install installs all of the dotnet-side packages needednpm ci downloads and audits correct versions of all of the npm packages. npm install will redo the versions if these have changed and generate an updated lock file.npm run dev, npm run dist, npm run debug: scripts defined in package.json which control developmment (with HMR) or production compilation with Fable, and packing using Webpack 5.build.cmd and build.sh scripts package the above steps adding some not usually necessary directory cleaning - you can run them individually in order if you have problems.dotnet-tools.json.paket.dependencies at top level and paket.references in the directory of the relevant .fsproj file. Currently dotnet packages are not pinned to versions so latest compatible versions are always used. This is probably wrong but seems to work well..d files. This works well, but manual adjutsment is needed for anything complex. See the Electon API interface in Issie which was generated in this way from a published electron API .d files - in that case the manual adjustment was quite unpleasant because Electron API is very complex.Electron bundles Chromium (View) and node.js (Engine), therefore as in every node.js project, the package.json file specifies the (Node) module dependencies.
Additionally, the section "scripts":
"scripts": {
"clean-dev-mac": "sudo killall -9 node && sudo killall -9 dotnet && sudo killall -9 issie",
"clean-dev-win": "taskkill /f /im node.exe && taskkill /f /im dotnet.exe && taskkill /f /im issie.exe",
"compile": "dotnet fable src/Main -s && dotnet fable src/Renderer -s --define PRODUCTION",
"debug": "dotnet fable watch src/Main -s --run npm run debugrenderer",
"debugrenderer": "dotnet fable watch src/Renderer -s --define ASSERTS --run npm run start",
"dev": "dotnet fable watch src/Main -s --run npm run devrenderer",
"devrenderer": "dotnet fable watch src/Renderer -s --run npm run start",
"start": "cross-env NODE_ENV=development node scripts/start.js",
"build": "cross-env NODE_ENV=production node scripts/build.js",
"pack": "npm run compile && npm run build && electron-builder --dir",
"dist": "npm run compile && npm run build && electron-builder",
"buildonly": "electron-builder",
"compile-sass": "cd src/renderer/scss && node-sass main.scss main.css",
"testcompiler": "cd src/Renderer/VerilogComponent/test && dotnet fable --noCache && node testParser.fs.js"
}Defines the in-project shortcut commands as a set of <key> : <value lines, so that when we use npm run <stript_key> it is equivalent to calling <script_value>.
For example, in the root of the project, running in the terminal npm run dev is equivalent to the command line:
dotnet fable watch src/Main -s --run npm run devrendererThis runs fable 4 to transpile the main process, then (--run is an option of fable to run another command) runs script devrenderer to transpile to javascript and watch the F# files in the renderer process. After the renderer transpilation is finished
start.js script will be run. This invokes webpack to pack and lauch the javascript code, under electron, and also watches for changes in the javascript code, and hot loads these on the running application
As result of this, at any time saving an edited F# renderer project file causes (nearly) immediate:
The build system depends on a Fake file build.fsx. Fake is a DSL written in F# that is specialised to automate build tasks. Build.fsx has targets representing build tasks, and normally these are run via build.cmd or build.sh, instead of using dotnet fake directly:
build <target> ==> dotnet fake build -t <target>The source code consists of two distinct sections transpiled separately to Javascript to make a complete Electron application.
Electron thus allows code written for a browser (HTML + CSS + JavaScript) to be run as a desktop app with the additional capability of desktop filesystem access via communication between the two processes.
Both processes run Javascript under Node.
The src/Main/Main.fs source configures electron start-up and is boilerplate. It is transpiled to the root project directory so it can be automatically picked up by Electron.
The remaining app code (in )
The code that turns the F# project source into renderer.js is the FABLE compiler followed by the Node Webpack bundler that combines multiple Javascript files into a single renderer.js.
The compile process is controlled by the .fsproj files (defining the F# source) and webpack.additions.main.js, webpack.additions.renderer.js
which define how Webpack combines F# outputs for both electron main and electron app processes and where the executable code is put.
This is boilerplate which you do not need to change; normally the F# project files are all that needs to be modified.
src folder| Subfolder or file | Description |
|---|---|
Main/main.fs |
Code for the main electron process that sets everything up - not normally changed |
Renderer/Common/* |
Provides some common types and utilities, as well as interfaces to libraries APIs and custom libraries |
Renderer/Interface/* |
Contains low-level interface functions, and all the low-level file management |
Renderer/DrawBlock/* |
Contains all the SVG-based schematic editor code in F# |
Renderer/Simulator/* |
Contains the logic to analyse and simulate a schematic sheet |
Renderer/UI/* |
Contains the UI logic |
./renderer.fs |
Top-level file that drives the renderer code: contains Elmish MVU loop and Electron menu code |
Tests folderCurrently tests are very old, and will not work. They are based on F# Expecto testing library and in principle the widthinferrer and simulator code (which runs under dotnet) could be tested here.
Static folderContains static files used in the application.
Docs folderContains source information that controls the project documentation web site https://tomcl.github.io/issie/.
Issie allows the users to create projects and files within those projects. A Issie project is simply a folder named <project-name> that contains an empty file named <project_name>.dprj (dprj stands for diagram project). The project folder any non-zero number of design files, each named <component_name>.dgm (dgm stands for diagram). each deisgn file represents one design sheet of a hierarchical hardware design, sheets can contain, as components, other sheets.
When opening a project, Issie will initially search the given repository for .dgm files, parse and load their content, and allow the user to open them in Issie or use them as components in other designs.
To reinstall the build environment (without changing project code) rerun build.cmd (Windows) or build.sh (Linux and MacOS).
npm run dist will generate the correct binaries for your system under /dist.