Add project files.
This commit is contained in:
EugeneTes
461
Inspectron.Epson/README.md
Normal file
461
Inspectron.Epson/README.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# Inspectron.Epson - Epson TM-m30III Printer SDK
|
||||
|
||||
A comprehensive C# SDK for the Epson TM-m30III thermal receipt printer, providing easy-to-use APIs for printing, status checking, and diagnostics.
|
||||
|
||||
## Features
|
||||
|
||||
- **Async/Await Pattern** - Modern asynchronous API throughout
|
||||
- **Connection Management** - Reliable TCP/IP connection handling
|
||||
- **Status Monitoring** - Comprehensive printer status queries
|
||||
- **Error Detection** - Detailed error reporting and diagnostics
|
||||
- **Printing Operations** - Simple text printing with ESC/POS commands
|
||||
- **Logging Support** - Optional ILogger integration for diagnostics
|
||||
- **Type-Safe** - Strong typing with C# records for status data
|
||||
|
||||
## Installation
|
||||
|
||||
Add the project reference to your solution:
|
||||
|
||||
```bash
|
||||
dotnet add reference path/to/Inspectron.Epson/Inspectron.Epson.csproj
|
||||
```
|
||||
|
||||
Or include the compiled DLL in your project.
|
||||
|
||||
### Dependencies
|
||||
|
||||
- .NET 8.0 or later
|
||||
- Microsoft.Extensions.Logging.Abstractions 8.0.0
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Printing
|
||||
|
||||
```csharp
|
||||
using Inspectron.Epson;
|
||||
|
||||
// Create printer instance
|
||||
await using var printer = new EpsonPrinter();
|
||||
|
||||
// Connect to printer
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
|
||||
// Print text with paper cut
|
||||
await printer.PrintTextAndCutAsync("Hello World!\nThis is a test receipt.");
|
||||
```
|
||||
|
||||
### With Logging
|
||||
|
||||
```csharp
|
||||
using Inspectron.Epson;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
// Create logger
|
||||
var loggerFactory = LoggerFactory.Create(builder =>
|
||||
{
|
||||
builder.AddConsole();
|
||||
builder.SetMinimumLevel(LogLevel.Information);
|
||||
});
|
||||
|
||||
var logger = loggerFactory.CreateLogger<EpsonPrinter>();
|
||||
|
||||
// Create printer with logging
|
||||
await using var printer = new EpsonPrinter(logger);
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
await printer.PrintTextAndCutAsync("Hello World!");
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Checking Printer Status
|
||||
|
||||
```csharp
|
||||
await using var printer = new EpsonPrinter();
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
|
||||
// Get overall status with health assessment
|
||||
var status = await printer.GetOverallStatusAsync();
|
||||
|
||||
Console.WriteLine($"Status: {status.StatusText}");
|
||||
Console.WriteLine($"Ready: {status.IsReady}");
|
||||
Console.WriteLine($"Model: {status.PrinterModel}");
|
||||
|
||||
if (!status.IsReady)
|
||||
{
|
||||
Console.WriteLine("Recommendations:");
|
||||
foreach (var recommendation in status.Recommendations)
|
||||
{
|
||||
Console.WriteLine($" - {recommendation}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Individual Status Queries
|
||||
|
||||
```csharp
|
||||
await using var printer = new EpsonPrinter();
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
|
||||
// Get specific status information
|
||||
var printerStatus = await printer.GetPrinterStatusAsync();
|
||||
Console.WriteLine($"Online: {printerStatus.IsOnline}");
|
||||
Console.WriteLine($"Cover Closed: {printerStatus.IsCoverClosed}");
|
||||
|
||||
var paperStatus = await printer.GetPaperSensorStatusAsync();
|
||||
Console.WriteLine($"Paper Present: {paperStatus.PaperPresent}");
|
||||
Console.WriteLine($"Paper Near End: {paperStatus.PaperNearEnd}");
|
||||
|
||||
var errorStatus = await printer.GetErrorStatusAsync();
|
||||
Console.WriteLine($"Has Error: {errorStatus.HasError}");
|
||||
Console.WriteLine($"Recoverable Error: {errorStatus.RecoverableError}");
|
||||
```
|
||||
|
||||
### Running Diagnostics
|
||||
|
||||
```csharp
|
||||
using Inspectron.Epson;
|
||||
|
||||
var diagnostics = new EpsonDiagnostics();
|
||||
var report = await diagnostics.RunFullDiagnosticsAsync("192.168.1.100");
|
||||
|
||||
Console.WriteLine(report);
|
||||
```
|
||||
|
||||
Sample diagnostic output:
|
||||
|
||||
```
|
||||
======================================================================
|
||||
EPSON TM-m30III PRINTER DIAGNOSTICS
|
||||
======================================================================
|
||||
Printer IP: 192.168.1.100:9100
|
||||
Timestamp: 2024-01-15 14:30:45
|
||||
======================================================================
|
||||
|
||||
⏳ Connecting to printer...
|
||||
✅ Connection established
|
||||
|
||||
⏳ Retrieving printer information...
|
||||
⏳ Querying printer status...
|
||||
|
||||
======================================================================
|
||||
OVERALL STATUS
|
||||
======================================================================
|
||||
|
||||
🟢 READY - Printer is operational
|
||||
|
||||
🖨️ Printer Model TM-m30III
|
||||
|
||||
======================================================================
|
||||
GENERAL PRINTER STATUS
|
||||
======================================================================
|
||||
📊 Raw Status Byte 0x12
|
||||
📊 Binary 00010010
|
||||
|
||||
✅ Printer Online YES
|
||||
✅ Cover Closed YES
|
||||
❌ Paper Feed Button Pressed NO
|
||||
❌ Drawer Open Signal NO
|
||||
```
|
||||
|
||||
### Advanced Printing
|
||||
|
||||
```csharp
|
||||
await using var printer = new EpsonPrinter();
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
|
||||
// Print without cutting
|
||||
await printer.PrintTextAsync("Line 1\n");
|
||||
await printer.PrintTextAsync("Line 2\n");
|
||||
await printer.PrintTextAsync("Line 3\n");
|
||||
|
||||
// Feed and cut
|
||||
await printer.SendRawCommandAsync(EpsonCommands.FeedLines(5));
|
||||
await printer.SendRawCommandAsync(EpsonCommands.CutPaperFull);
|
||||
```
|
||||
|
||||
### Sending Raw ESC/POS Commands
|
||||
|
||||
```csharp
|
||||
await using var printer = new EpsonPrinter();
|
||||
await printer.ConnectAsync("192.168.1.100");
|
||||
|
||||
// Use predefined commands
|
||||
await printer.SendRawCommandAsync(EpsonCommands.Initialize);
|
||||
await printer.PrintTextAsync("Initialized printer\n");
|
||||
|
||||
// Or create custom commands
|
||||
byte[] customCommand = { 0x1B, 0x40 }; // ESC @ (Initialize)
|
||||
await printer.SendRawCommandAsync(customCommand);
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### EpsonPrinter Class
|
||||
|
||||
Main class for printer operations.
|
||||
|
||||
#### Constructor
|
||||
|
||||
```csharp
|
||||
public EpsonPrinter(ILogger<EpsonPrinter>? logger = null)
|
||||
```
|
||||
|
||||
Creates a new printer instance with optional logging support.
|
||||
|
||||
#### Connection Methods
|
||||
|
||||
```csharp
|
||||
Task ConnectAsync(string ip, int port = 9100, int timeoutSeconds = 5)
|
||||
```
|
||||
|
||||
Connect to the printer at the specified IP address and port.
|
||||
|
||||
```csharp
|
||||
void Disconnect()
|
||||
```
|
||||
|
||||
Disconnect from the printer.
|
||||
|
||||
```csharp
|
||||
bool IsConnected { get; }
|
||||
```
|
||||
|
||||
Returns true if currently connected to the printer.
|
||||
|
||||
#### Status Query Methods
|
||||
|
||||
```csharp
|
||||
Task<PrinterStatus> GetPrinterStatusAsync()
|
||||
```
|
||||
|
||||
Get general printer status (online, cover, drawer, etc.).
|
||||
|
||||
```csharp
|
||||
Task<OfflineStatus> GetOfflineStatusAsync()
|
||||
```
|
||||
|
||||
Get offline status (reasons why printer is offline).
|
||||
|
||||
```csharp
|
||||
Task<ErrorStatus> GetErrorStatusAsync()
|
||||
```
|
||||
|
||||
Get error status (recoverable, unrecoverable, cutter errors).
|
||||
|
||||
```csharp
|
||||
Task<PaperSensorStatus> GetPaperSensorStatusAsync()
|
||||
```
|
||||
|
||||
Get paper sensor status (paper present, near end).
|
||||
|
||||
```csharp
|
||||
Task<string?> GetPrinterIdAsync()
|
||||
```
|
||||
|
||||
Get printer model/ID string.
|
||||
|
||||
```csharp
|
||||
Task<OverallStatus> GetOverallStatusAsync()
|
||||
```
|
||||
|
||||
Get comprehensive status with health assessment and recommendations.
|
||||
|
||||
#### Printing Methods
|
||||
|
||||
```csharp
|
||||
Task PrintTextAsync(string text)
|
||||
```
|
||||
|
||||
Print text to the printer.
|
||||
|
||||
```csharp
|
||||
Task PrintTextAndCutAsync(string text, int feedLines = 5)
|
||||
```
|
||||
|
||||
Print text, feed paper, and cut.
|
||||
|
||||
```csharp
|
||||
Task SendRawCommandAsync(byte[] command)
|
||||
```
|
||||
|
||||
Send raw ESC/POS command bytes.
|
||||
|
||||
### EpsonDiagnostics Class
|
||||
|
||||
Comprehensive diagnostics tool.
|
||||
|
||||
```csharp
|
||||
public EpsonDiagnostics(ILogger<EpsonDiagnostics>? logger = null)
|
||||
```
|
||||
|
||||
```csharp
|
||||
Task<string> RunFullDiagnosticsAsync(string ip, int port = 9100, int timeoutSeconds = 5)
|
||||
```
|
||||
|
||||
Run full diagnostic check and return formatted report.
|
||||
|
||||
### Status Data Models
|
||||
|
||||
All status classes are immutable records with these common properties:
|
||||
|
||||
- `byte RawByte` - Raw status byte from printer
|
||||
- `string Binary` - Binary representation (8 bits)
|
||||
- `string Hex` - Hexadecimal representation
|
||||
|
||||
#### PrinterStatus
|
||||
|
||||
- `bool DrawerOpen` - Drawer kick-out connector pin 3 is HIGH
|
||||
- `bool IsOnline` - Printer is online
|
||||
- `bool IsCoverClosed` - Cover is closed
|
||||
- `bool PaperFeedButtonPressed` - Paper feed button is pressed
|
||||
|
||||
#### OfflineStatus
|
||||
|
||||
- `bool CoverOpen` - Cover is open (offline reason)
|
||||
- `bool PaperFeedButton` - Paper feed button active (offline reason)
|
||||
- `bool PaperEnd` - Paper end detected (offline reason)
|
||||
- `bool ErrorOccurred` - Error occurred (offline reason)
|
||||
|
||||
#### ErrorStatus
|
||||
|
||||
- `bool RecoverableError` - Recoverable error occurred
|
||||
- `bool AutoCutterError` - Auto-cutter error occurred
|
||||
- `bool UnrecoverableError` - Unrecoverable error occurred
|
||||
- `bool AutoRecoveryError` - Auto-recovery error occurred
|
||||
- `bool HasError` - True if any error is present
|
||||
|
||||
#### PaperSensorStatus
|
||||
|
||||
- `bool PaperNearEnd` - Paper roll is near end
|
||||
- `bool PaperPresent` - Paper is present
|
||||
|
||||
#### OverallStatus
|
||||
|
||||
- `string? PrinterModel` - Printer model/ID
|
||||
- `PrinterStatus? PrinterStatus` - General printer status
|
||||
- `OfflineStatus? OfflineStatus` - Offline status
|
||||
- `ErrorStatus? ErrorStatus` - Error status
|
||||
- `PaperSensorStatus? PaperStatus` - Paper sensor status
|
||||
- `string StatusText` - Overall status description
|
||||
- `bool IsReady` - True if printer is ready
|
||||
- `List<string> Recommendations` - List of recommendations
|
||||
- `string StatusIcon` - Status emoji (🟢/🟡/🟠/🔴/❓)
|
||||
|
||||
### EpsonCommands Class
|
||||
|
||||
Static class containing ESC/POS command constants:
|
||||
|
||||
- `byte[] Initialize` - Initialize printer (ESC @)
|
||||
- `byte[] GetPrinterStatus` - DLE EOT 1
|
||||
- `byte[] GetOfflineStatus` - DLE EOT 2
|
||||
- `byte[] GetErrorStatus` - DLE EOT 3
|
||||
- `byte[] GetPaperSensorStatus` - DLE EOT 4
|
||||
- `byte[] GetPrinterId` - GS I 1
|
||||
- `byte[] CutPaperFull` - Full paper cut (GS V 0)
|
||||
- `byte[] CutPaperPartial` - Partial paper cut (GS V 1)
|
||||
- `byte[] FeedLines(byte lines)` - Feed n lines (ESC d n)
|
||||
- `byte[] LineFeed` - Line feed (LF)
|
||||
|
||||
### Exception Types
|
||||
|
||||
#### EpsonPrinterException
|
||||
|
||||
Base exception for all Epson printer errors.
|
||||
|
||||
#### EpsonConnectionException
|
||||
|
||||
Thrown when connection fails or is lost.
|
||||
|
||||
Properties:
|
||||
- `string? PrinterIp` - Printer IP address
|
||||
- `int? PrinterPort` - Printer port
|
||||
|
||||
#### EpsonCommandException
|
||||
|
||||
Thrown when a command fails.
|
||||
|
||||
Properties:
|
||||
- `byte[]? Command` - The command that failed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**Problem:** Cannot connect to printer
|
||||
|
||||
**Solutions:**
|
||||
- Verify printer IP address is correct
|
||||
- Ensure printer is powered on
|
||||
- Check network connectivity (ping the printer)
|
||||
- Verify printer is on the same network
|
||||
- Check firewall settings
|
||||
- Ensure port 9100 is accessible
|
||||
|
||||
### Timeout Errors
|
||||
|
||||
**Problem:** Operations timeout
|
||||
|
||||
**Solutions:**
|
||||
- Increase timeout parameter in ConnectAsync
|
||||
- Check printer is not busy with another job
|
||||
- Verify printer is not in an error state
|
||||
- Check network latency
|
||||
|
||||
### Printer Offline
|
||||
|
||||
**Problem:** Printer shows as offline
|
||||
|
||||
**Solutions:**
|
||||
- Check cover is closed
|
||||
- Ensure paper is loaded
|
||||
- Clear any error conditions
|
||||
- Check offline status for specific reasons
|
||||
|
||||
### Paper Issues
|
||||
|
||||
**Problem:** Paper not detected or near end
|
||||
|
||||
**Solutions:**
|
||||
- Load paper roll correctly
|
||||
- Ensure paper is feeding through sensor
|
||||
- Replace paper if near end
|
||||
- Check paper roll is compatible
|
||||
|
||||
### Auto-Cutter Errors
|
||||
|
||||
**Problem:** Cutter error reported
|
||||
|
||||
**Solutions:**
|
||||
- Check for paper jams in cutter
|
||||
- Remove any obstructions
|
||||
- Open and close cover to reset
|
||||
- May require service if persistent
|
||||
|
||||
## Technical Details
|
||||
|
||||
### ESC/POS Protocol
|
||||
|
||||
This SDK uses ESC/POS commands via TCP/IP on port 9100. The DLE EOT (0x10 0x04) real-time status commands are used for status queries.
|
||||
|
||||
### Status Byte Format
|
||||
|
||||
All status responses follow the format: `0xx1xx10b` where:
|
||||
- Bit 7: Always 0
|
||||
- Bits 6,5,3,2: Status-specific flags
|
||||
- Bit 4: Always 1
|
||||
- Bits 1,0: Fixed pattern (10b)
|
||||
|
||||
### Connection
|
||||
|
||||
- Protocol: TCP/IP
|
||||
- Default Port: 9100
|
||||
- Character Encoding: UTF-8 for text, ASCII for responses
|
||||
- Timeout: Configurable (default 5 seconds)
|
||||
|
||||
## License
|
||||
|
||||
Copyright Inspectron. All rights reserved.
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or contributions, please contact the development team.
|
||||
Reference in New Issue
Block a user