Add project files.
This commit is contained in:
EugeneTes
258
CLAUDE.md
Normal file
258
CLAUDE.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a C# .NET 8.0 solution for Epson TM-m30III thermal receipt printer integration. The solution consists of a core SDK library (Inspectron.Epson) and multiple applications for production printing, configuration, testing, and discovery.
|
||||
|
||||
## Solution Structure
|
||||
|
||||
### Core Projects
|
||||
|
||||
- **Inspectron.Epson** - Core SDK library providing printer communication, status monitoring, and ESC/POS commands
|
||||
- **EpsonPrintService** - Production console application with SignalR-based remote job source and systemd service support
|
||||
- **ConfigurationPannel** - ASP.NET Razor Pages web application for printer configuration with embedded print server
|
||||
- **Discovery** - Printer network discovery utilities (SLP, ENPC, mDNS)
|
||||
- **EpsonTest** - Test project for SDK functionality
|
||||
- **TestClient** - SDK usage examples and testing
|
||||
- **SendPrintJob** - Direct print job submission utility
|
||||
|
||||
## Common Build Commands
|
||||
|
||||
```bash
|
||||
# Build entire solution
|
||||
dotnet build Inspectron.Epson.slnx
|
||||
|
||||
# Build specific project
|
||||
dotnet build Inspectron.Epson/Inspectron.Epson.csproj
|
||||
dotnet build EpsonPrintService/EpsonPrintService.csproj
|
||||
dotnet build ConfigurationPannel/ConfigurationPannel.csproj
|
||||
|
||||
# Run projects
|
||||
dotnet run --project EpsonPrintService/EpsonPrintService.csproj
|
||||
dotnet run --project ConfigurationPannel/ConfigurationPannel.csproj
|
||||
|
||||
# Run tests
|
||||
dotnet test EpsonTest/EpsonTest.csproj
|
||||
|
||||
# Clean build artifacts
|
||||
dotnet clean
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Three-Layer Architecture
|
||||
|
||||
1. **SDK Layer (Inspectron.Epson)**
|
||||
- `EpsonPrinter`: Main facade for printer operations (TCP/IP, async/await)
|
||||
- `EpsonCommands`: Static ESC/POS command definitions
|
||||
- `EpsonImageConverter`: Image processing with Floyd-Steinberg dithering
|
||||
- `EpsonPrinterDiscovery`: Network printer discovery (SLP, ENPC)
|
||||
- Status classes: PrinterStatus, OfflineStatus, ErrorStatus, PaperSensorStatus, OverallStatus
|
||||
- Exception hierarchy: EpsonPrinterException → EpsonConnectionException, EpsonCommandException
|
||||
|
||||
2. **Print Server Layer (PrintServer/ namespace in Inspectron.Epson)**
|
||||
- `PrintServer`: Manager for printer queues, coordinates multiple printers by IP
|
||||
- `PrinterQueue`: Per-printer queue with retry logic (ConcurrentQueue + priority ConcurrentStack)
|
||||
- `PrintLoop`: Orchestrator connecting job sources to print server
|
||||
- `IPrintJobSource`: Strategy pattern for job sources (SignalRPrintJobSource, SingleJobSource, NoOpPrintJobSource)
|
||||
- `IPrintService`: Print workflow orchestration (EpsonPrintService implementation)
|
||||
- `IPrinter`: Printer model abstraction (TM-T30III, TM-U220II)
|
||||
- `PrinterFactory`: Factory pattern for creating printer instances by model ID
|
||||
|
||||
3. **Application Layer**
|
||||
- EpsonPrintService: Production deployment with Ninject DI, SignalR remote jobs, systemd service
|
||||
- ConfigurationPannel: ASP.NET Core with Microsoft.Extensions.DI, cookie authentication, hosted service pattern
|
||||
|
||||
### Dependency Injection Patterns
|
||||
|
||||
The codebase uses TWO different DI containers:
|
||||
|
||||
**Ninject (EpsonPrintService console app):**
|
||||
```csharp
|
||||
StandardKernel kernel = new();
|
||||
kernel.Bind<IPrintJobSource, SignalRPrintJobSource>().To<SignalRPrintJobSource>().InSingletonScope();
|
||||
kernel.Bind<IPrintService>().To<EpsonPrintService>();
|
||||
kernel.Bind<IAssignedPrinterRepository>().ToConstant(config);
|
||||
kernel.Bind<IPrinterFactory>().To<PrinterFactory>().InSingletonScope();
|
||||
kernel.Bind<PrintServer>().ToSelf().InSingletonScope();
|
||||
```
|
||||
|
||||
**Microsoft.Extensions.DependencyInjection (ConfigurationPannel ASP.NET):**
|
||||
```csharp
|
||||
builder.Services.AddSingleton<UserService>();
|
||||
builder.Services.AddSingleton<ConfigurationManager>();
|
||||
builder.Services.AddHostedService<PrintServerHostedService>();
|
||||
```
|
||||
|
||||
When adding new services, match the DI pattern of the project you're working in.
|
||||
|
||||
### Key Interfaces and Abstractions
|
||||
|
||||
- `IPrintJobSource`: Pluggable job sources (async via Channel<PrintJob>)
|
||||
- `IPrintService`: Print workflow execution (PrintAsync returns bool for success/failure)
|
||||
- `IAssignedPrinterRepository`: Maps work area IDs to printer IPs (GetAssignedPrinter)
|
||||
- `IPrinterConfigurationSource`: Provides printer configuration (address, font size, logo)
|
||||
- `IPrinter`: Printer model-specific operations (InitAsync, PrintImageAsync, SetFontSizeAsync, PrintTextAsync, Cut)
|
||||
- `IPrinterFactory`: Creates IPrinter from model ID byte (0x01 = TM-T30III, 0x13 = TM-U220II)
|
||||
|
||||
### Print Job Flow
|
||||
|
||||
```
|
||||
PrintLoop.StartAsync()
|
||||
→ IPrintJobSource.GetNextJobAsync() [blocks until job available]
|
||||
→ IAssignedPrinterRepository.GetAssignedPrinter(job.AreaId) [returns printer IP]
|
||||
→ PrintServer.SubmitJob(printerIp, job)
|
||||
→ PrinterQueue.Enqueue(job) [per-printer queue]
|
||||
→ ProcessQueueAsync() [background loop]
|
||||
→ IPrintService.PrintAsync(printerIp, job)
|
||||
→ Get configuration, connect to printer, detect model
|
||||
→ IPrinterFactory.CreatePrinterFromId()
|
||||
→ Initialize printer, print logo (if configured), set font size
|
||||
→ Print text content, cut paper
|
||||
→ Return true/false for success
|
||||
→ On failure: retry up to 3 times via priority queue
|
||||
```
|
||||
|
||||
### Configuration System
|
||||
|
||||
**EpsonPrintServiceConfiguration** (config.json):
|
||||
```json
|
||||
{
|
||||
"GroupId": "67e534f8e86e816689323023",
|
||||
"RestaurantId": "63e37295bd6f26dbd36164c0",
|
||||
"PrinterConfigurations": {
|
||||
"192.168.1.100": {
|
||||
"Address": "192.168.1.100:9100",
|
||||
"FontSize": 2,
|
||||
"LogoFilename": "logo.png",
|
||||
"AreaId": "kitchen"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This class implements BOTH `IPrinterConfigurationSource` and `IAssignedPrinterRepository` for dual roles.
|
||||
|
||||
### Printer Communication
|
||||
|
||||
- **Protocol**: ESC/POS over TCP/IP (port 9100 default)
|
||||
- **Encoding**: UTF-8 (ESC t 255) or CP852 (ESC t 18) with System.Text.Encoding.CodePages
|
||||
- **Status Queries**: DLE EOT real-time commands (0x10 0x04 + sub-command byte)
|
||||
- **Image Printing**: Two modes
|
||||
- Raster mode (GS ( L): 384px width for TM-T30III
|
||||
- Bit-image mode (ESC *): 8-dot or 24-dot with single/double density
|
||||
- **Error Handling**: All async operations throw EpsonConnectionException or EpsonCommandException on failure
|
||||
|
||||
## Adding New Printer Models
|
||||
|
||||
1. Get printer ID byte via `EpsonPrinter.GetPrinterIdAsync()` (GS I 1 command)
|
||||
2. Create new class implementing `IPrinter` in `Inspectron.Epson/PrintServer/Printers/`
|
||||
3. Implement required methods: InitAsync, PrintImageAsync, SetFontSizeAsync, PrintTextAsync, Cut
|
||||
4. Add case to `PrinterFactory.CreatePrinterFromId()` with the printer ID byte
|
||||
5. Test with actual hardware - different models have different image widths and positioning
|
||||
|
||||
## Testing Printer Connectivity
|
||||
|
||||
```csharp
|
||||
// Basic connection test
|
||||
await using var printer = new EpsonPrinter(logger);
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
var status = await printer.GetOverallStatusAsync();
|
||||
Console.WriteLine($"Status: {status.StatusText}, Ready: {status.IsReady}");
|
||||
|
||||
// Full diagnostics
|
||||
var diagnostics = new EpsonDiagnostics(logger);
|
||||
var report = await diagnostics.RunFullDiagnosticsAsync("192.168.1.100");
|
||||
Console.WriteLine(report);
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Systemd Service (Linux)
|
||||
|
||||
EpsonPrintService includes systemd service file (`epson.service`):
|
||||
```bash
|
||||
# Copy files to deployment directory
|
||||
cp -r EpsonPrintService/bin/Debug/net8.0/* /home/pi/epson_service/
|
||||
|
||||
# Install and start service
|
||||
sudo cp epson.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable epson.service
|
||||
sudo systemctl start epson.service
|
||||
|
||||
# Check status
|
||||
sudo systemctl status epson.service
|
||||
```
|
||||
|
||||
### ASP.NET Hosted Service
|
||||
|
||||
ConfigurationPannel runs print server as `IHostedService`:
|
||||
```bash
|
||||
dotnet run --project ConfigurationPannel/ConfigurationPannel.csproj
|
||||
```
|
||||
Access web UI at http://localhost:5000 (default login credentials in users.json).
|
||||
|
||||
## Important Implementation Notes
|
||||
|
||||
### PrinterQueue Retry Logic
|
||||
|
||||
Failed print jobs are automatically retried up to 3 times via priority queue:
|
||||
- Failed jobs pushed to `ConcurrentStack<PrintJob>` (LIFO)
|
||||
- Priority stack checked before main queue in `ProcessQueueAsync()`
|
||||
- RetryCount incremented on each failure
|
||||
- Jobs with RetryCount >= 3 are discarded
|
||||
|
||||
### Image Processing Pipeline
|
||||
|
||||
When printing images via `EpsonPrinter.LoadImageAsync()`:
|
||||
1. Load image with SixLabors.ImageSharp
|
||||
2. Resize maintaining aspect ratio (max width: printer-specific)
|
||||
3. Convert to grayscale
|
||||
4. Apply Floyd-Steinberg dithering for 1-bit black/white conversion
|
||||
5. Pack pixels to byte-aligned format
|
||||
6. Generate column format for bit-image mode (ESC * 33)
|
||||
|
||||
### SignalR Job Source
|
||||
|
||||
`SignalRPrintJobSource` connects to `https://api.gastrojames.ch/hubs/internal`:
|
||||
- Authentication: Bearer token from configuration
|
||||
- Group: Joins via GroupId from configuration
|
||||
- Message: "PrintJob" with { WorkingAreaId, Content }
|
||||
- Uses Channel<PrintJob> for async producer-consumer pattern
|
||||
|
||||
### Font Sizing
|
||||
|
||||
Font magnification is 1-8x for both width and height:
|
||||
- ESC ! command: bits 4-7 control size
|
||||
- Formula: `(widthMagnifier - 1) << 4 | (heightMagnifier - 1)`
|
||||
- Example: Size 2 = 0x11 (2x width, 2x height)
|
||||
|
||||
## Common Troubleshooting
|
||||
|
||||
### "Printer not found" or connection timeout
|
||||
- Verify IP address with `ping <printer-ip>`
|
||||
- Check printer is on same network/VLAN
|
||||
- Ensure port 9100 is not blocked by firewall
|
||||
- Try printer discovery: run Discovery project
|
||||
|
||||
### "Cover open" or "Paper end" errors
|
||||
- Check `OverallStatus.Recommendations` for specific issues
|
||||
- Common: Cover not fully closed, paper roll empty/misaligned
|
||||
|
||||
### Image not printing or garbled
|
||||
- Verify image width matches printer specification (384px for TM-T30III)
|
||||
- Check image file path is accessible
|
||||
- Ensure printer model supports raster graphics (TM-T30III does, older models may not)
|
||||
|
||||
### SignalR connection failures
|
||||
- Check GroupId and RestaurantId in config.json
|
||||
- Verify network connectivity to api.gastrojames.ch
|
||||
- Check bearer token expiration
|
||||
|
||||
### ConfigurationPannel login issues
|
||||
- Default credentials in users.json (BCrypt hashed)
|
||||
- Cookie expiration: 8 hours with sliding expiration
|
||||
- Authentication uses CookieAuthenticationDefaults scheme
|
||||
Reference in New Issue
Block a user