{"id":31057177,"url":"https://github.com/shishir-dey/callisto","last_synced_at":"2026-06-08T16:33:24.262Z","repository":{"id":312244625,"uuid":"1046145589","full_name":"shishir-dey/Callisto","owner":"shishir-dey","description":"probe-rs based ITM viewer for Cortex-M","archived":false,"fork":false,"pushed_at":"2025-08-29T11:41:08.000Z","size":50,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T13:21:20.139Z","etag":null,"topics":["embedded-systems","firmware-tools","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shishir-dey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T08:57:44.000Z","updated_at":"2025-08-29T11:41:12.000Z","dependencies_parsed_at":"2025-08-29T13:23:30.024Z","dependency_job_id":"8dfa2f63-5e94-4b8f-aab5-fbd285acf0ab","html_url":"https://github.com/shishir-dey/Callisto","commit_stats":null,"previous_names":["shishir-dey/callisto"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shishir-dey/Callisto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shishir-dey%2FCallisto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shishir-dey%2FCallisto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shishir-dey%2FCallisto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shishir-dey%2FCallisto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shishir-dey","download_url":"https://codeload.github.com/shishir-dey/Callisto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shishir-dey%2FCallisto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275219532,"owners_count":25425888,"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","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["embedded-systems","firmware-tools","vibe-coding"],"created_at":"2025-09-15T06:51:23.678Z","updated_at":"2026-06-08T16:33:24.221Z","avatar_url":"https://github.com/shishir-dey.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Callisto ITM Viewer\n\nA real-time ITM (Instrumentation Trace Macrocell) viewer for embedded systems development. Callisto provides a modern, Apple-inspired interface for visualizing trace data from ARM Cortex-M microcontrollers.\n\n## Quick Start\n\n### Prerequisites\n\n- **Rust** (latest stable) - [Install via rustup](https://rustup.rs/)\n- **Node.js** 18+ - [Download](https://nodejs.org/)\n- **pnpm** - `npm install -g pnpm`\n- **just** - `cargo install just`\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/callisto-itm/callisto.git\ncd callisto\n\n# Set up development environment\njust setup\n\n# Start the application\njust dev\n```\n\nThis will:\n1. Install all dependencies\n2. Generate TypeScript types from JSON schemas\n3. Start the server on `127.0.0.1:9229`\n4. Launch the Electron client with device selection\n5. Automatically detect available debug probes\n\n## Architecture\n\nCallisto consists of three main components:\n\n```\n┌─────────────────┐    WebSocket     ┌─────────────────┐\n│  Electron App   │ ◄─────────────► │  Rust Server    │\n│  (Client UI)    │                 │  (Data Bridge)  │\n└─────────────────┘                 └─────────────────┘\n                                             │ probe-rs\n                                             ▼\n                                    ┌─────────────────┐\n                                    │  Debug Probe    │\n                                    │  (ST-Link, etc) │\n                                    └─────────────────┘\n                                             │ SWD/JTAG\n                                             ▼\n                                    ┌─────────────────┐\n                                    │  Target MCU     │\n                                    │  (ARM Cortex-M) │\n                                    └─────────────────┘\n```\n\n### Server (Rust)\n- **Protocol**: WebSocket message definitions with JSON schema generation\n- **Core**: ITM processing engine with probe-rs integration\n- **CLI**: WebSocket server with real-time event streaming\n\n### Client (Electron + React)\n- **Viewer**: Desktop application with timeline and performance charts\n- **Types**: Generated TypeScript definitions from JSON schemas\n\n### Embedded Libraries\n- **C Header**: `callisto_trace.h` for C/C++ projects\n- **Rust Crate**: `callisto-trace` for embedded Rust projects\n\n## Features\n\n### Device Discovery\n- **Automatic Detection**: Scans for connected debug probes using probe-rs\n- **Mock Support**: Built-in mock device for testing without hardware\n- **Dynamic Switching**: Change devices without restarting the application\n- **Visual Interface**: Modern device selection modal with clear indicators\n\n### Modern UI\n- **Light/Dark Themes**: Toggle between themes with instant switching\n- **Card-Based Layout**: Timeline and performance charts in distinct, bordered cards\n- **Apple-Inspired Design**: Clean, modern interface with smooth animations\n- **Responsive**: Adapts to different window sizes and screen densities\n\n### Real-Time Visualization\n- **Timeline View**: Live ITM event stream with syntax highlighting\n- **Performance Charts**: CPU load, event rate, and throughput monitoring\n- **Event Filtering**: Filter by port, event type, or custom criteria\n- **Export/Import**: Save and load trace sessions (coming soon)\n\n## Usage\n\n### Getting Started\n\n1. **Launch Application**: Run `just dev` to start both server and client\n2. **Select Device**: Choose from detected probes or use mock device for testing\n3. **Connect**: Click connect to establish communication with your target\n4. **Start Tracing**: Begin capturing ITM data from your embedded application\n\n### Embedded Integration\n\n#### C/C++ Projects\n\n```c\n#include \"callisto_trace.h\"\n\nint main() {\n    // Initialize ITM tracing\n    callisto_trace_init(0x0F); // Enable ports 0-3\n    \n    // Send text messages\n    callisto_puts(\"System initialized\");\n    \n    // Send markers\n    callisto_marker(42);\n    \n    // RTOS events\n    callisto_task_switch(1, 2);\n    callisto_isr_enter(10);\n    callisto_isr_exit(10);\n    \n    while (1) {\n        callisto_idle_enter();\n        __WFI(); // Wait for interrupt\n        callisto_idle_exit();\n        \n        // Your application code...\n    }\n}\n```\n\n#### Rust Projects\n\n```rust\nuse callisto_trace::*;\n\nfn main() -\u003e ! {\n    // Initialize global ITM\n    let itm = init_global();\n    \n    // Send trace data\n    itm.console().puts(\"Hello from Rust!\");\n    itm.markers().marker(123);\n    itm.rtos().task_switch(1, 2);\n    \n    loop {\n        // Your application code...\n    }\n}\n```\n\n### ITM Port Map\n\n| Port | Name | Purpose | Decoder |\n|------|------|---------|---------|\n| 0 | Console | Text output | Text |\n| 1 | RTOS | Task/ISR events | TaskIsr |\n| 2 | Markers | Timestamped markers | Marker |\n| 3 | Counters | Performance counters | Counter |\n| 4-31 | User | Custom data | User-defined |\n\n### WebSocket Protocol\n\nConnect to `ws://127.0.0.1:9229/ws` for real-time ITM data:\n\n```javascript\nconst ws = new WebSocket('ws://127.0.0.1:9229/ws');\n\nws.onmessage = (event) =\u003e {\n  const message = JSON.parse(event.data);\n  \n  switch (message.type) {\n    case 'Hello':\n      console.log('Connected:', message.data.version);\n      break;\n    case 'Event':\n      console.log('ITM Event:', message.data);\n      break;\n    case 'Stats':\n      console.log('Performance:', message.data);\n      break;\n  }\n};\n```\n\n## Development\n\n### Commands\n\n```bash\n# Development\njust dev          # Start development environment\njust build        # Build everything\njust test         # Run all tests\njust clean        # Clean build artifacts\n\n# Code Quality\njust lint         # Lint all code\njust fmt          # Format all code\njust check        # Check project health\n\n# Utilities\njust typegen      # Generate TypeScript types\njust docs         # Generate documentation\njust status       # Show project status\n```\n\n### Project Structure\n\n```\ncallisto/\n├── server/                 # Rust server workspace\n│   ├── protocol/          # WebSocket protocol definitions\n│   ├── core/              # ITM processing engine\n│   └── cli/               # WebSocket server binary\n├── client/                # Node.js client workspace\n│   ├── apps/viewer-electron/  # Electron + React app\n│   └── shared/types/      # Generated TypeScript types\n├── schema/ws/             # JSON schemas\n├── docs/                  # Documentation\n├── callisto-trace/        # Embedded Rust library\n├── callisto_trace.h       # Embedded C library\n└── justfile              # Development commands\n```\n\n### Adding New Event Types\n\n1. **Protocol**: Add to `TraceEvent` enum in [`server/protocol/src/lib.rs`](server/protocol/src/lib.rs)\n2. **Server**: Implement decoder in [`server/core/src/decoder.rs`](server/core/src/decoder.rs)\n3. **Client**: Add UI handling in [`client/apps/viewer-electron/src/components/Timeline.tsx`](client/apps/viewer-electron/src/components/Timeline.tsx)\n4. **Types**: Regenerate with `just typegen`\n\n## Documentation\n\n- **[Device Discovery](docs/device-discovery.md)**: Device detection, UI enhancements, and management\n- **[Protocol](docs/protocol.md)**: WebSocket message format and ITM port assignments\n- **[Architecture](docs/architecture.md)**: System design and component overview\n- **[Development Workflow](docs/dev-workflow.md)**: Contributing guidelines and best practices\n\n## Hardware Support\n\n### Supported Debug Probes\n- **ST-Link V2/V3** (STMicroelectronics) - Full support with automatic detection\n- **J-Link** (Segger) - All models supported via probe-rs\n- **CMSIS-DAP** compatible probes - Standard ARM debug interface\n- **Black Magic Probe** - Open source debug probe\n- **Custom Probes** - Any probe-rs supported device\n\n### Supported Microcontrollers\n- **ARM Cortex-M series**: M0, M0+, M3, M4, M7, M33, M55\n- **STM32 family**: All series with ITM support\n- **Nordic nRF series**: nRF52, nRF53, nRF91\n- **NXP LPC/Kinetis series**: LPC4xxx, LPC5xxx, Kinetis K/L series\n- **Atmel/Microchip SAM series**: SAMD, SAME, SAMV\n\n### Requirements\n- **ITM Support**: Most Cortex-M3/M4/M7 devices (check datasheet)\n- **SWO Connection**: SWO pin connected to debug probe\n- **Firmware Setup**: ITM enabled and configured in target application\n- **Debug Probe**: Connected via USB and recognized by operating system\n\n### Device Detection\nThe application automatically scans for connected probes on startup:\n- **Real-time Scanning**: Refresh device list without restarting\n- **Status Indicators**: Clear visual feedback for device availability\n- **Fallback Mode**: Mock device available when no hardware detected\n- **Error Handling**: Graceful handling of disconnected or busy probes\n\n## Performance\n\n- **Throughput**: Up to 500KB/s with USB 2.0 debug probes\n- **Latency**: \u003c10ms end-to-end typical\n- **Event Rate**: 10,000+ events/second sustained\n- **Memory**: \u003c50MB server, \u003c500MB client\n- **CPU**: \u003c5% on modern systems\n\n## Troubleshooting\n\n### Common Issues\n\n**\"No devices found\" or empty device list**\n- Ensure debug probe is connected via USB\n- Check that probe drivers are installed (ST-Link, J-Link, etc.)\n- Try refreshing the device list using the refresh button\n- Verify probe is not in use by another application (IDE, debugger)\n- Use `just list-probes` command to verify probe detection\n\n**\"Failed to connect to device\"**\n- Ensure target microcontroller is powered and connected\n- Verify SWO pin is properly connected to debug probe\n- Check that no other debugging session is active\n- Try selecting a different device or using mock device\n\n**\"ITM data not received\"**\n- Verify ITM is enabled and configured in target firmware\n- Check SWO baud rate matches server configuration (typically 2MHz)\n- Ensure target CPU frequency is correctly configured\n- Verify ITM stimulus ports are enabled (ports 0-31)\n\n**\"WebSocket connection failed\"**\n- Check server is running on port 9229\n- Verify firewall is not blocking the connection\n- Try restarting with `just server`\n- Check for port conflicts with other applications\n\n**\"Server startup failed\" or \"Address already in use\"**\n- Another server instance may be running - stop it first\n- Check if port 9229 is in use by another application\n- Try restarting the entire development environment with `just dev`\n\n### Debug Mode\n\n```bash\n# Enable debug logging\nRUST_LOG=debug just server\n\n# Monitor WebSocket traffic\nwebsocat ws://127.0.0.1:9229/ws\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [development workflow](docs/dev-workflow.md) for guidelines.\n\n### Quick Contribution Setup\n\n```bash\n# Fork the repository on GitHub\ngit clone https://github.com/YOUR_USERNAME/callisto.git\ncd callisto\n\n# Set up development environment\njust setup\n\n# Create feature branch\ngit checkout -b feature/amazing-feature\n\n# Make changes and test\njust test\njust lint\n\n# Commit and push\ngit commit -m \"feat: add amazing feature\"\ngit push origin feature/amazing-feature\n\n# Create pull request on GitHub\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshishir-dey%2Fcallisto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshishir-dey%2Fcallisto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshishir-dey%2Fcallisto/lists"}