Issie - an Interactive Schematic Simulator with Integrated Editor

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.

• If you are just interested in using the application, jump to the Getting Started section.
• If you want user documentation and news go to the web pages.
• If you are interested in a more detailed description of Issie please check out the Wiki.

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.

Introduction

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 schematic 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:

• The success of the VisUAL2, which uses a similar technology stack;
• Strongly typed functional code tends to be easy to maintain and test, as the type-checker massively helps you;
• Imperial College EEE/EIE students learn such language in the 3rd year High-Level-Programming course, hence can maintain the app in the future;
• F# can be used with the powerful Elmish framework to develop User Interfaces in a Functional Reactive Programming fashion.

Getting Started

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.

• Windows: unzip *.zip anywhere and double-click the top-level Issie.exe application in the unzipped files.
  • If you get a security warning saying something like: Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk. More info then:
    • Click More Info
    • Then click Run Anyway
• Macos: Double click the dmg file and run the application inside the folder, or drag and drop this to install.
  • If Macos asks you to do this, you will need to change your security settings to allow apps not downloaded from app store
  • Apple -> System settings -> Privacy & Security -> (find at bottom of options by scrolling) Allow Applications From -> App Store and Known Developers

Issie 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.

Getting Started as Developer

If you want to get started as a developer, follow these steps.

Development Install Prerequisites (common to windows, macos, linux)

Download and install (if you already have these tools installed just check the version constraints).

• .Net 8 SDK.
• Node.js v22.
  • You do not need to install chocolatey (at the prompt for this) however you can if you want
  • Node.js includes the npm package manager, so this does not need to be installed separately.
    • However as of Dec 2024 v22 node does not include the necessary latest v11 npm. After installing node you must update npm as follows
      • npm install -g npm@latest
      • After upgrade npm --version should return 11.x.x
  • If you are using a different version of Node for development on other projects, global install (the default) may interfere with this. You will need to do a more complex local node install.
• (recommended) Visual Studio 2022 which includes F# 8.0, Install with:
  • Workload: .Net Desktop development
  • Ticked: F# language support
• (recommended) install hyper.js or Windows Terminal for Windows. On windows change terminal settings if needed so terminal runs cmd window not powershell.

Issie Development

1. Download & unzip the Issie repo, or clone it locally, or fork it on github and then clone it locally.

   • If downloading as zip you must on Windows unblock the zip file's MOTW mark. In file explorer, right-clik on the zip file and select properties. Then click unblock.
   • Afte unblocking extract all files from the zip file as normal.

2. Check you have the .NET and Node prerequisites above if you want to do more than make binaries, also: VS 2022 (or latest VS Code + ionide, or Rider) installed.

   • In a terminal window: node -v shows Node version. dotnet --version shows Dotnet version.

3. Navigate from the repo master branch root directory (which contains this README), in a command-line interpreter, or start one from directory context menu.

4. Run build.cmd under Windows or build.sh under linux or macos (chmod 755 build.sh will give the script execute permission). This will download and install all dependencies then launch the application in dev mode with HMR.

• HMR: the application will automatically recompile and update while running if you save updated source files
• To initialise and reload: File -> reload page
• To exit: after you exit the application the auto-compile script will terminate after about 15s
• To recompile the whole application again run npm run dev. Run npm run debug for the debug mode (this is going to be a lot slower than dev).
• To generate distributable binaries for dev host system npm run dist.
• If you have changed packet.json and therefore need to remake the lock file paket-lock.json use npm install.
• On windows build killzombies will terminate orphan node and dotnet processes which occasionally happen using this build chain after unusual terminations (maybe no longer needed?)

6. To make binaries only. Cancel dev mode (two ctrl-C in command window) if it is running. Run npm run dist in command window to generate binaries under .\dist directory. For macos you will need to install python 3 to compile native binaries - you will be auto-prompted to do this but will then need to run npm run dist again.

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 Visual Studio. Compilation should be identical but when unsure why there is an error it is very helpful to build the current code under .Net with 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.

Node management details

• package-lock.json contains exact package versions and is downloaded from the repo. Normally you don't need to change this. The standard bui