Teaching assembly language has a tooling problem. Most university courses use the LC-3 — a 16-bit instruction set architecture with 16 opcodes and 8 registers, simple enough to teach in a semester, complex enough to demonstrate how a CPU actually works. The standard simulator is a desktop application last updated years ago. Students write code, assemble it, step through execution, and when they get stuck — why did the zero flag set? why is R2 holding the wrong value? — they're on their own.
This walkthrough builds a browser-based LC-3 assembly tutor that solves both problems. The VM runs entirely client-side via C compiled to WebAssembly, so every instruction executes at near-native speed with zero latency. An AI tutor powered by Telnyx Inference sees the full machine state and answers contextual questions about what's happening at each step.
The canonical code example lives in the Telnyx code examples repo:
https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-assembly-tutor-c
Live demo: https://ai-assembly-tutor-v2-9a6d593b-1.telnyxcompute.com/
What This Example Builds
A three-panel browser application for interactive assembly language learning:
| Panel | What it shows |
|---|---|
| Left — Code Editor | Write LC-3 assembly, click Assemble, load example programs |
| Center — VM State | 8 registers (R0–R7) in hex/decimal, condition flags (N/Z/P), memory viewer centered on PC, output console |
| Right — AI Tutor | Chat interface with quick-ask buttons, contextual explanations from DeepSeek-V4.1-Flash |
The application has two modes of execution:
- Step — Execute one instruction. The UI updates registers, flags, and memory after each step so students can trace exactly what the machine does.
- Run — Execute instructions continuously (~100 per frame) until HALT. Useful for programs where step-by-step is tedious.
Five example programs are included: Hello World, Add Numbers, Countdown (loop with branch), Fibonacci, and Calculator (I/O with TRAP routines).
Why This Matters
The LC-3 AI Assembly Tutor exercises two Telnyx products in a real educational workflow — AI Inference for the tutor and Edge Compute for the entire hosting stack. The architecture demonstrates a pattern that extends beyond assembly language: a compute-intensive client (WASM), a knowledge API (LLM inference), and a thin backend that connects them.
Developers and educators use this pattern for:
- Interactive assembly courses — Replace desktop simulators with a browser tool that includes an AI teaching assistant
- Computer architecture labs — Give students a VM they can step through with explanations at every instruction
- Self-paced learning — A tutor available 24/7 that never gets tired of explaining why the P flag set after an ADD
- Code review tools — The same pattern (code context + AI explanation) applies to any language
- WASM-powered educational tools — Compile existing C/C++ tools to run in the browser
Products Used
telnyx_products: [AI Inference, Edge Compute]
Telnyx AI Inference provides the intelligence — DeepSeek-V4.1-Flash answers student questions with full VM context (registers, flags, current instruction, source code). Telnyx Edge Compute hosts the entire application — a single TypeScript file that embeds all frontend assets and serves the AI tutor API endpoint.
Architecture
Browser (Client-Side)
┌─────────────────────────────────────────────┐
│ Code Editor → Two-Pass Assembler (JS) │
│ ↓ │
│ LC-3 VM (C → WASM, 379 lines) │
│ ├─ 16 opcodes, 8 registers, N/Z/P flags │
│ ├─ 65,536-word memory, programs at x3000 │
│ └─ TRAP routines (GETC, OUT, PUTS, HALT) │
│ ↓ │
│ VM State Panel (registers, flags, memory) │
│ │
│ AI Tutor Panel ─────────────────────────────┤
│ │ POST /api/explain │
└──┴───────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────┐
│ Telnyx Edge Compute (edge/index.ts) │
│ ├─ Serves all static assets (embedded) │
│ ├─ Rate limiting (20 req/min per IP) │
│ └─ Calls Telnyx Inference API │
└──────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────┐
│ Telnyx Inference API │
│ POST /v2/ai/openai/chat/completions │
│ Model: deepseek-ai/DeepSeek-V4.1-Flash │
│ Temperature: 0.3 (precise explanations) │
│ Max tokens: 4096 │
└──────────────────────────────────────────────┘
The LC-3 Virtual Machine
The VM is 379 lines of C compiled to WebAssembly via Emscripten. It implements the complete LC-3 instruction set:
| Opcode | Mnemonic | Purpose |
|---|---|---|
| 0 | BR | Branch (conditional on N/Z/P flags) |
| 1 | ADD | Add (register or 5-bit immediate) |
| 2 | LD | Load (PC-relative addressing) |
| 3 | ST | Store (PC-relative) |
| 4 | JSR/JSRR | Jump to subroutine |
| 5 | AND | Bitwise AND (register or 5-bit immediate) |
| 6 | LDR | Load register (base + 6-bit offset) |
| 7 | STR | Store register (base + offset) |
| 9 | NOT | Bitwise NOT |
| 10 | LDI | Load indirect (double dereference) |
| 11 | STI | Store indirect |
| 12 | JMP/RET | Jump or return from subroutine |
| 14 | LEA | Load effective address (not memory contents) |
| 15 | TRAP | System call (GETC, OUT, PUTS, IN, PUTSP, HALT) |
The C code exports functions through Emscripten for JavaScript to call:
EXPORT void vm_init(void); // Reset VM
EXPORT void vm_load_program(uint16_t *p, int n); // Load binary at x3000
EXPORT int vm_step(void); // Execute 1 instruction, return opcode
EXPORT uint16_t vm_get_register(int r); // Read R0-R7, PC (8), COND (9)
EXPORT uint16_t vm_get_memory(uint16_t addr); // Read a memory word
EXPORT int vm_is_halted(void); // Check if HALT was executed
EXPORT const char* vm_get_output(void); // Get buffered TRAP output
EXPORT void vm_clear_output(void); // Clear output buffer
EXPORT void vm_queue_input(char c); // Queue input for GETC/IN
The JavaScript WASM bridge calls these via cwrap:
export async function loadVM() {
Module = await LC3Module();
vmInit = Module.cwrap('vm_init', null, []);
vmStep = Module.cwrap('vm_step', 'number', []);
vmGetRegister = Module.cwrap('vm_get_register', 'number', ['number']);
vmGetMemory = Module.cwrap('vm_get_memory', 'number', ['number']);
vmIsHalted = Module.cwrap('vm_is_halted', 'number', []);
vmGetOutput = Module.cwrap('vm_get_output', 'string', []);
vmClearOutput = Module.cwrap('vm_clear_output', null, []);
}
The Two-Pass Assembler
The assembler is 388 lines of JavaScript running entirely client-side. It compiles LC-3 assembly source to a Uint16Array binary.
Pass 1 scans for labels and builds a symbol table:
// If the first token isn't an opcode or directive, it's a label
if (!(first in OPCODES) && !first.startsWith('.')) {
symbols[tokens[0].toUpperCase()] = addr; // Label → address
}
Pass 2 encodes instructions, resolving label references into PC-relative offsets:
case 1: // ADD
instr = (opcode << 12) | (dr << 9) | (sr1 << 6);
if (immediate_flag) {
instr |= (1 << 5) | fitBits(imm5, 5); // Immediate mode
} else {
instr |= sr2; // Register mode
}
Supported directives: .ORIG (set origin address), .END (end of program), .FILL (store literal), .BLKW (allocate block), .STRINGZ (null-terminated string).
The AI Tutor
When a student asks a question, the frontend builds a context object containing the full VM state:
const context = {
registers: { R0: 0x3003, R1: 0x0000, /* ... */ },
pc: 'x3002',
flags: { N: false, Z: false, P: true },
halted: false,
currentInstruction: 'PUTS',
lastOpcode: 'LEA',
code: '.ORIG x3000\n LEA R0, HELLO\n PUTS\n HALT\n...'
};
The Edge backend formats this into a user message and sends it to Telnyx Inference:
const payload = {
model: 'deepseek-ai/DeepSeek-V4.1-Flash',
messages: [
{ role: 'system', content: SYSTEM_PROMPT },
{ role: 'user', content: userMessage }
],
max_tokens: 4096,
temperature: 0.3
};
The system prompt encodes deep LC-3 domain knowledge — all 16 opcodes, addressing modes, condition flag behavior, TRAP routines, and common student misconceptions (like the difference between LEA and LD, or how BR checks flags set by the previous instruction).
The Edge Compute Backend
The entire backend is a single TypeScript file (edge/index.ts, 743 lines). It embeds all frontend assets as string constants:
const ASSETS: Record<string, { content: string | Buffer; type: string }> = {};
ASSETS['/'] = { type: 'text/html; charset=utf-8', content: `<!DOCTYPE html>...` };
ASSETS['/style.css'] = { type: 'text/css; charset=utf-8', content: `...` };
// JavaScript modules, WASM glue...
const WASM_B64 = 'AGFzbQEAAAABFgV...'; // WASM binary as base64
const WASM_BUF = Buffer.from(WASM_B64, 'base64');
The HTTP server routes requests to static assets, the WASM binary, or the AI endpoint:
const server = http.createServer(async (req, res) => {
if (url === '/api/explain' && req.method === 'POST') {
// Rate limit → parse body → build context → call Inference → return response
}
if (url === '/wasm/lc3.wasm') {
// Serve WASM binary from buffer
}
if (ASSETS[url]) {
// Serve embedded static asset
}
});
Deploy with one command:
cd edge
npm install
telnyx-edge ship
Try the Live Demo
Open the live demo in any modern browser:
https://ai-assembly-tutor-v2-9a6d593b-1.telnyxcompute.com/
- Click an example program (start with Hello World)
- Click Assemble to compile the source
- Click Step to execute one instruction at a time
- Watch registers, flags, and memory update in the center panel
- Click "What does this do?" or type a question to ask the AI tutor
Run It Locally
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-assembly-tutor-c
Build the WASM VM (requires Emscripten):
bash build.sh
# Outputs: web/wasm/lc3.js + web/wasm/lc3.wasm
Serve the frontend locally:
cd web
python3 -m http.server 8080
# Open http://localhost:8080
Deploy the Edge backend:
cd ../edge
cp .env.example .env # Add your TELNYX_API_KEY
npm install
telnyx-edge ship
Going to Production
This example is a working demo. For production deployment:
- Conversation memory — Add conversation history to the AI tutor so students can have multi-turn discussions ("Why did the flag change?" → "What would happen if I used BRn instead?")
- Breakpoints — Let students set breakpoints and run until a specific address, instead of stepping instruction by instruction through long programs
- Code sharing — URL-encode programs so students can share links to their code with the AI's state
- Persistent sessions — Store student progress and conversation history server-side
- Model selection — Test different models for accuracy on LC-3 specifics; DeepSeek-V4.1-Flash is fast and accurate, but larger models may give more detailed explanations for complex programs
- Rate limiting — The demo's in-memory rate limiter works for a single instance; production needs Redis or a distributed counter
- Error recovery — If inference fails, show a friendly message instead of a broken chat panel