{"id":15060482,"url":"https://github.com/lmichaelis/computer-simulation","last_synced_at":"2025-04-10T05:54:18.676Z","repository":{"id":48635161,"uuid":"96862725","full_name":"lmichaelis/Computer-Simulation","owner":"lmichaelis","description":"A simulation of Ben Eater's breadboard computer which can run assembly code","archived":false,"fork":false,"pushed_at":"2021-07-16T16:18:36.000Z","size":37,"stargazers_count":20,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-06T17:06:27.225Z","etag":null,"topics":["assembly-language","cpu-emulator","python3","simulation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lmichaelis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-11T07:13:48.000Z","updated_at":"2024-02-08T18:47:31.000Z","dependencies_parsed_at":"2022-08-27T05:52:38.574Z","dependency_job_id":null,"html_url":"https://github.com/lmichaelis/Computer-Simulation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmichaelis%2FComputer-Simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmichaelis%2FComputer-Simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmichaelis%2FComputer-Simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmichaelis%2FComputer-Simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lmichaelis","download_url":"https://codeload.github.com/lmichaelis/Computer-Simulation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166927,"owners_count":21058480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly-language","cpu-emulator","python3","simulation"],"created_at":"2024-09-24T22:59:19.102Z","updated_at":"2025-04-10T05:54:18.644Z","avatar_url":"https://github.com/lmichaelis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nThis software simulates the breadboard computer made\nby Ben Eater. You can write programs for it\nusing Ben Eaters assembly language or\ndirectly write binary code.\nIt was made by Luis Michaelis. You are allowed\nto edit this program and redistribute it as\nit is free and open source software.\n\n## Setup \u0026 Usage\n\nFor this program to run you will need\nPython 3.6 which you can download for all\nplatforms from [python.org](https://www.python.org/).\n\nTo start open a terminal or command-line window\nin the folder of the program. Type in:\n\n``` shell\n    python[3] cpu.py test.prg.bin\n```\n\nFor linux users the command is python3\nThis will launch the included test program\nwhich counts up until it reaches 256, then\nit counts down until it reaches 0 and does\nthis in a loop. To see the assembly code just\nopen the test.prg in your favourite text\neditor. This code needs to be compiled before\nit can be used. To compile the code type in\na terminal:\n\n``` shell\n    python[3] compiler.py test.prg\n```\n\nThis will compile the assembly code stored in\ntest.prg into the compiled file test.prg.bin.\nYou can open this file with a text editor too\nand see the compiled binary code.\n\nTo summarize:\nYou can compile your program using:\n\n``` shell\n    python[3] compile.py [yourfilename]\n```\n\nYou can run the program by typing:\n\n``` shell\n    python[3] cpu.py [youfilename].bin\n```\n\nUnless your program has a specific HLT instruction, the program will run forever.\n\nTo exit the program gracefully, send a KeyboardInterrupt (CTRL+C).\n\nFor more information about the programs\ntype:\n    python[3] [program].py -h\n\n## Writing Code\n\nYou can write your code either in Ben Eater's\nassembly language or directly write binary code.\nFor convenience, here the table of assembly\ncode, binary representation and description:\n\n|Assembly | Binary    | Description                                                   | Argument\n|--------|-----------|---------------------------------------------------------------|----------------------------\n|NOP      | 0000 xxxx | Do nothing (No Operation)                                     | Not Required (set to 0)\n|LDA      | 0001 xxxx | Load value from RAM into the A register (Load A)              | Required (memory location)\n|ADD      | 0010 xxxx | Add a value from RAM to the value in the A register and put the result back into the A register (Add) | Required (memory location)\n|SUB      | 0011 xxxx | Subtract a value from RAM from the value in the A register and put the result back into the A register (Subtract) | Required (memory location)\n|STA      | 0100 xxxx | Store the value in the A register into RAM (Store A)          | Required (memory location)\n|LDI      | 0101 xxxx | Load a immediately using the argument (Load immediately)      | Required (number to load)\n|JMP      | 0110 xxxx | Jump to a specified 'line' in code (!Lines start at 0) (Jump) | Required (line number)\n|JPC      | 0111 xxxx | Jump to a specified 'line' in code (!Lines start at 0) if the result of the previous operation was less than 0 or more than 255 (Jump Carry) | Required (line number)\n|JPZ      | 1000 xxxx | Jump to a specified 'line' in code (!Lines start at 0) if the result of the previous operation was equal to 0 (Jump if Zero) | Required (line number)\n|OUT      | 1110 xxxx | Write the value in the A register to the CLI (Output)         | Not Required (set to 0)\n|HLT      | 1111 xxxx | Halt the system (Halt)                                        | Not Required (set to 0)\n\n## Rules\n\n- Line starts either with instruction or memory\n  address and colon:\n\nAssembly:\n\n```asm\nADD 15\n15: 5\n```\n\nBinary:\n\n```text\n0010 1111\n1111: 00000101\n```\n\nLine with memory address specifies variable address:variable\nLine without specifies instruction\n\n- Except variables (255/0b11111111), all given numbers may not be\n  larger than 15/0b1111\n\n- Hashes (#) introduce comments\n\n- PLEASE NOTE THAT MEMORY LOCATIONS WILL OVERWRITE IF\n  THEY ARE SET MULTIPLE TIMES. This also applies for\n  instructions: Every instruction gets automatically\n  a space in memory, starting at 0000 and incrementing\n  by one for every detected instruction:\n\nAssembly\n\n```asm\nLDA 15  # Memory address 0\nOUT 0   # Memory address 1 (and so on ...)\n\n15: 6   # Memory address 15\n```\n\nBinary\n\n```text\n0001 1111 # Memory address 0\n1110 0000 # Memory address 1 (and so on ...)\n\n1111: 00000110 # Memory address 15\n```\n\nThe simulation program (cpu.py) can only run compiled\nbinary code which could either be written by yourself\nor be result of the compiler. The compiler (compiler.py)\nonly compiles assembly files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmichaelis%2Fcomputer-simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flmichaelis%2Fcomputer-simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmichaelis%2Fcomputer-simulation/lists"}