REST API

Smartreader Embedded REST API Documentation

Overview

This document describes the REST API endpoints available in the Smartreader Embedded application. The API provides functionality for managing reader settings, monitoring tag data, controlling inventory operations, and handling various system configurations.

Authentication

All endpoints are protected with Basic Authentication. Include the following header in your requests:

Authorization: Basic <base64-encoded-credentials>

Default credentials are admin/admin.

Base URL

All API endpoints are relative to the base URL: https://<reader-ip>:8443

Endpoints

Streaming Endpoints

Get Volume Stream

GET /api/stream/volumes

Streams volume data in Server-Sent Events (SSE) format. Returns array of JSON documents containing volume information.

  • Success response: 200 OK with an endless SSE stream of JSON payloads. Idle intervals emit {} keep-alive events every ~10 seconds so the connection stays open.

  • Error responses: 401 Unauthorized when the Basic credentials are wrong; transport errors close the stream.

  • Side effects: None—events are read-only and do not mutate state.

Clear Stream Summaries

Resets all cached stream summary data before starting a new inventory cycle or when preparing to replay SSE output. Use this endpoint when you need the next stream to emit only fresh summary data so dashboards and downstream processors do not blend results from previous runs.

  • Success Response: 204 No Content indicates the summary buffers were cleared successfully and the reader is ready to accumulate new metrics.

  • Error Responses: 401 Unauthorized if the request lacks valid credentials, and 500 Internal Server Error if the reader cannot clear the cached summaries.

Clearing summaries ensures the next inventory cycle begins with a clean state. Until new data is collected, subsequent GET /api/stream/volumes and GET /api/stream/tags calls will not include previously aggregated summaries.

Get Tags Stream

Streams tag read data in Server-Sent Events (SSE) format. Returns array of JSON documents containing tag information.

  • Success response: 200 OK SSE stream. Each event removes the emitted tag record from the runtime database, so replays require a fresh accumulation cycle.

  • Error responses: 401 Unauthorized for bad credentials.

  • Side effects: Delivered events are deleted from SmartReaderTagReadModels, preventing duplicate delivery.

Get Task Events Stream

Streams task progress updates in Server-Sent Events (SSE) format without requiring the deprecated logical point segment. The stream ends when the task completes or is removed. Always prefer this convenience route; legacy clients that still rely on logical-point-prefixed paths should migrate as those endpoints are scheduled for removal.

Guidance: Always reset stream summaries with DELETE /api/stream/clear-summaries before restarting an inventory or replaying a stream so that consumers receive only data from the new session.

Task Management

SmartReader exposes task lifecycle operations under /api/v1/tasks. The Basic Auth credential is required for every call.

List Tasks

  • Success response: 200 OK with an array of TaskDefinition objects that include taskId, logicalPointId, state, and any embedded documents.

  • Error response: 401 Unauthorized when credentials are invalid.

  • Side effects: None.

Create Task

  • Success response: 201 Created with the persisted task echoing back in the body.

  • Validation failure: Missing logicalPointId returns 400 Bad Request and the plain-text message LogicalPointId is required from the controller.

  • Side effects: The controller calls ITaskService.CreateTaskAsync, causing the task to be stored and tracked for progress events.

Get Task by ID

  • Success response: 200 OK with a TaskDefinition resolved from persisted metadata.

  • Error response: 404 Not Found when the ID does not exist.

  • Side effects: None.

Update Task by ID

  • Success response: 200 OK with the merged task payload after the service updates it with the stored logical point.

  • Error response: 404 Not Found when the task cannot be resolved to a logical point.

  • Side effects: Updates the task persisted by ITaskService.UpdateTaskAsync, which may trigger downstream progress events.

Delete Task by ID

  • Success response: 204 No Content once the task is removed from the service.

  • Error response: 404 Not Found if the controller cannot resolve the task/logical point pair.

  • Side effects: Deletes the task and raises a TaskRemoved event, which closes any connected SSE streams.

Task Progress Snapshot

  • Success response: 200 OK with a TaskProgress DTO containing state, percentage, and EPC collections.

  • Error response: 404 Not Found when no task or progress exists for the ID.

Task Progress Stream (SSE)

  • Success response: 200 OK streaming data: {...} events until the task completes or is removed. The controller listens for TaskProgressUpdated and TaskRemoved notifications and tears down the stream afterward.

  • Error response: 404 Not Found if the task cannot be resolved before the stream starts.

  • Side effects: None on invocation; consumers simply tap into existing task lifecycle events.

Manage Task Documents

  • Success response: 201 Created with the stored DocumentDefinition when the task exists.

  • Error response: 404 Not Found if the task ID cannot be mapped to a logical point.

  • Update: PUT /api/v1/tasks/task/{taskId}/documents/{documentId} accepts the same JSON and returns 200 OK with the revised document.

  • Delete: DELETE /api/v1/tasks/task/{taskId}/documents/{documentId} responds with 204 No Content after removal.

  • Side effects: Document calls mutate the task’s stored document set inside ITaskService, immediately affecting subsequent task executions and SSE payloads.

Legacy logical-point-prefixed routes (for example, POST /api/v1/tasks/{logicalPointId}) are still available but deprecated; they call the same service methods and return identical DTOs.

System Configuration

Get Settings

Retrieves current reader configuration settings.

  • Success response: 200 OK with an array containing the StandaloneConfigDTO pulled from the runtime database or config file (for example [{ "readerName": "R700-01", "antennaPorts": "1,2,3,4", ... }]).

  • Error response: 404 Not Found if no configuration is persisted.

Update Settings

Updates reader configuration settings. Accepts a StandaloneConfigDTO object containing the configuration parameters.

  • Success response: 200 OK with { "message": "Settings saved successfully." }. The controller persists the JSON into ReaderConfigs, stores any supplied license in READER_LICENSE, and notifies _grpcPublisherService.UpdateConfig so running jobs pick up the change.

  • Error response: 400 Bad Request with { "message": "Error saving settings." } when the update fails (for example, serialization issues).

  • Side effects: Overwrites the reader configuration in the database and can enable dependent services such as advanced GPO or HTTP integrations on the next inventory cycle.

Restore Default Settings

Resets all settings to their default values.

  • Success response: 200 OK returning the factory StandaloneConfigDTO and resetting Basic Auth to admin/admin when customsettings.json is present.

  • Error response: 404 Not Found if the default template cannot be loaded.

  • Side effects: SaveConfigDtoToDb writes the defaults back to storage, wiping any customizations.

Device Information

Get Serial Number

Retrieves the reader's serial number.

  • Success response: 200 OK containing a list of serial DTOs pulled from ReaderStatus (for example [ { "serialNumber": "370123456789" } ]).

  • Error response: 404 Not Found if the serial cache is empty.

Get Device ID

Retrieves the reader's device identifier.

  • Success response: 200 OK with { "readerName": "R700-01" } sourced from StandaloneConfigDTO.

  • Error response: 404 Not Found if no name is configured.

Get Status

Retrieves the current operational status of the reader.

  • Success response: 200 OK with the JSON previously persisted in ReaderStatus (running inventory status snapshots).

  • Error response: 404 Not Found when no status entry exists.

Get Capabilities

Retrieves the reader's capabilities including supported features and limitations.

  • Success response: 200 OK with a SmartReaderCapabilities payload describing antennas, search modes, and RF tables.

  • Error response: 500 Internal Server Error when capability discovery fails; the body contains { "message": "..." }.

Get RFID Status

Retrieves the current RFID subsystem status.

  • Success response: 200 OK with key/value pairs parsed from the RShell show rfid stat output.

  • Error response: Always 200 OK with whatever data could be gathered; failures log internally.

Get Image Status

Retrieves information about the current system image.

  • Success response: 200 OK with a dictionary of RShell image summary fields (for example {"version":"7.0.0.0","build":"2024-09-15"}).

  • Error response: Returns 200 OK with partial data if parsing fails; the controller logs any exceptions.

Inventory Control

Start Preset

Starts the preset inventory operation.

  • Success response: 200 OK with { "message": "Command START_PRESET queued." }. The optional barcode is cached for validation and the controller enqueues ReaderCommands entry START_PRESET/START before persisting it.

  • Error response: 200 OK with { "message": "Error queueing START_PRESET." } if an exception occurs; the log records the failure.

  • Side effects: Adds a command row that downstream jobs poll to launch the preset workflow.

Stop Preset

Stops the preset inventory operation.

  • Success response: 200 OK with { "message": "Command STOP_PRESET queued." } after persisting a stop command.

  • Side effects: Cancels the preset workflow by enqueuing STOP_PRESET/STOP.

Start Inventory

Starts a new inventory operation.

  • Success response: 200 OK with { "message": "Command START_INVENTORY queued." }. The barcode is cached and ReaderCommands receives the START_INVENTORY/START row for the inventory service.

  • Side effects: Launches the configured job pipeline once the command processor consumes the queued record.

Stop Inventory

Stops the current inventory operation.

  • Success response: 200 OK with { "message": "Command STOP_INVENTORY queued." } after persisting the stop command.

  • Side effects: Terminates the running job via the command queue.

GPIO Control

Set GPO Status

Controls the General Purpose Output (GPO) pins.

  • Success response: 200 OK with { "message": "GPO 1 set to High", "timestamp": "..." } when the port number is between 1 and 3 and the status is on/off (case insensitive).

  • Error response: 400 Bad Request with a descriptive message if the port is outside the supported range or the status string is invalid.

  • Side effects: Invokes _gpoService.SetGpoStateAsync to immediately drive the hardware output line.

Parameters:

  • port: Integer value specifying the GPO port number

  • status: String value ("ON"/"OFF" or "1"/"0") specifying the desired state

Get GPO Configuration

Returns the current configuration for all ports.

  • Success response: 200 OK with an ExtendedGpoConfigurationRequest listing the three supported ports, control modes, and states.

  • Error response: 500 Internal Server Error with an ErrorResponse body if the configuration cannot be retrieved.

  • Side effects: None; this is a read-only query.

Update GPO Configuration

Updates the configuration for all GPO ports.

  • Success response: 200 OK with a SuccessResponse summarising the updated ports.

  • Validation errors: 400 Bad Request with a ValidationErrorResponse when the payload is missing, ports are out of range, or control/state combinations are invalid.

  • Error response: 500 Internal Server Error with an ErrorResponse for unexpected failures.

  • Side effects: Persists the configuration via _gpoService.UpdateConfigurationAsync, immediately affecting subsequent inventory jobs.

Set GPO State

Sets a static state for an individual port.

  • Success response: 200 OK with { "message": "GPO 1 set to High", ... } when the payload passes validation.

  • Validation failure: 400 Bad Request if the port is outside 1-3 or the state property is missing/invalid.

  • Error response: 500 Internal Server Error when the service throws.

  • Side effects: Calls _gpoService.SetGpoStateAsync to toggle the hardware line immediately.

Pulse GPO

Generates a pulse on the specified port.

  • Success response: 200 OK with { "message": "GPO 2 pulsed for 750ms", ... } when the duration is within the configured bounds.

  • Validation failure: 400 Bad Request if the port is invalid or the duration falls outside 100–MaxPulseDurationMs.

  • Error response: 500 Internal Server Error when the pulse command fails.

  • Side effects: _gpoService.PulseGpoAsync drives the output high for the requested interval, then returns it to the previous state.

Set GPO Network Control

Puts the port into network control mode.

  • Success response: 200 OK with { "message": "GPO 3 set to network control mode", ... } when the feature is allowed in configuration.

  • Validation failure: 400 Bad Request if network control is disabled or the port is outside 1-3.

  • Error response: 500 Internal Server Error when the service fails to update the port.

  • Side effects: Switches the port to network-controlled mode so external systems can drive it over TCP/IP.

Reset GPO Configuration

Resets all GPOs to their default configuration.

  • Success response: 200 OK with { "message": "All 3 GPOs reset to default configuration", ... }.

  • Error response: 500 Internal Server Error with an ErrorResponse when the reset fails.

  • Side effects: Calls _gpoService.ResetToDefaultAsync, reverting each port to static low output.

Get GPO Status

  • Success response: 200 OK with a GpoStatusResponse that lists each port’s control mode, state, pulse duration, and health flag.

  • Error response: 500 Internal Server Error with an ErrorResponse if the status cannot be retrieved.

  • Side effects: None; this endpoint reflects current configuration and runtime status only.

Get Supported GPO Modes

Lists all supported control modes and port limits.

  • Success response: 200 OK with a ControlModesResponse containing supported control modes, port ranges, and pulse duration limits.

  • Side effects: None—this is a static capability query driven by configuration values.

System Management

Operation Type Management

GET /api/operation-type

Loads the workflow mode from the standalone configuration file and returns it as an OperationTypeDto.

  • Request parameters: None. The controller simply calls ConfigFileHelper.ReadFile() to deserialize /customer/config/smartreader.json and inspect StandaloneConfigDTO.operationType.

  • Success response:

    Returned with 200 OK when the persisted configuration contains a non-empty workflow mode.

  • 404 Not Found: Returned when the configuration file is missing or the value is blank.

POST /api/operation-type

Accepts an OperationTypeDto payload to update the reader's workflow mode.

Field
Type
Required
Description

operationType

string

Yes

New workflow identifier to store in StandaloneConfigDTO.operationType.

  • Validation: Requests without a body or with an empty operationType property receive 400 Bad Request with { "message": "Invalid operation type." }.

  • Success workflow:

    A valid request results in 200 OK with the updated value echoed back to the caller.

Workflow update flow

  1. StatusController.SetOperationType merges the incoming value with the existing configuration (creating a new StandaloneConfigDTO when needed).

  2. The controller persists the updated DTO via ConfigFileHelper.SaveFile, overwriting /customer/config/smartreader.json so the new workflow survives device restarts and is reloaded by any service that reads the config during the workflow update pipeline.

  3. Subsequent GET /api/operation-type calls and downstream workflow automation features (for example, the workflow update jobs described in this guide) surface the newly stored mode without additional client action.

Reminder: Legacy logical-point-prefixed task endpoints remain deprecated. Use the /api/v1/tasks routes for all task lifecycle operations.

Clean Filter

Cleans the EPC software history filters.

  • Success response: 200 OK with { "message": "Software filter history cleaned." } after queuing CLEAN_EPC_SOFTWARE_HISTORY_FILTERS in the ReaderCommands table.

  • Error response: 500 Internal Server Error with { "message": "Error cleaning filter." } when the command cannot be recorded.

  • Side effects: Downstream jobs purge cached EPC reads as soon as the queued command is processed.

Clear Validation Cache

Flushes any cached SKU validation results maintained by the background validation service. Use this endpoint when validation rules are updated, new product data is loaded, or the cache TTL has been temporarily extended and stale reads must be removed immediately. Returns 200 OK with a confirmation message when the cache is successfully cleared or 500 Internal Server Error if the cache could not be purged.

  • Success response: 200 OK with { "message": "Validation cache cleared." } after invoking _validationService.ClearValidation().

  • Error response: 500 Internal Server Error with { "message": "Error clearing validation cache." } when the service throws.

  • Side effects: Forces the next validation cycle to fetch fresh catalog data instead of relying on cached entries.

Validation Cache TTL Configuration

The validation cache lifetime defaults to 300 seconds, as defined by ValidationCacheOptions.CacheTtlSeconds in the application service configuration. The same value appears in reader settings as validationCacheTtlInSec, allowing operators to override the TTL via /api/settings updates, the Reader Settings UI, or the /customer/appsettings.json file. When a custom TTL is applied, the validation background service reloads the value at runtime and enforces the updated expiration policy. For broader context on how the validation background service manages cached reads, see the Validation feature documentation.

Reload System

Reloads the reader application.

  • Success response: 200 OK with { "message": "Application is restarting." } after enqueuing START_INVENTORY/START and calling Environment.Exit(0) to trigger a restart.

  • Error response: 200 OK with { "message": "Error during reload." } if the restart fails.

  • Side effects: Terminates the process, so issue the command only when the reader can safely reboot.

Upgrade Firmware

Initiates a firmware upgrade process.

  • Success response: 200 OK with { "message": "Upgrade firmware command queued." } when a firmware URL is configured, otherwise { "message": "Upgrade firmware URL not configured." }.

  • Error response: 200 OK with { "message": "Error queueing upgrade command." } if queuing fails.

  • Side effects: Adds UPGRADE_SYSTEM_IMAGE to ReaderCommands, prompting the firmware worker to download and install the image.

Verify License Key

Verifies a license key.

  • Success response: 200 OK with [ { "isValid": "pass" | "fail" } ] depending on the MD5 hash comparison between the supplied key and the reader serial.

  • Error handling: Exceptions are swallowed; the controller still returns [ { "isValid": "fail" } ].

  • Side effects: None—this is a read-only validation check.

Restore Configuration

Restores the reader configuration from backup.

  • Success response: 200 OK with { "message": "Restore initiated." } after copying smartreader_backup.json over the active config and exiting with code 1.

  • Error response: 200 OK with { "message": "Error during restore." } if the operation fails.

  • Side effects: Forces an application restart using the restored configuration file.

Clean USB Files

Removes files from the USB storage. Optional query parameter filename to delete a specific file.

  • Success response: 200 OK with either { "message": "All files cleaned successfully" } or { "message": "File 'export.json' deleted successfully" } depending on the query string.

  • Error responses: 404 Not Found when the directory or file is missing, 500 Internal Server Error for IO failures.

  • Side effects: Permanently deletes files from /customer/wwwroot/files. Use cautiously in production workflows.

Metrics

Returns current reader metrics in Prometheus text format.

  • Success response: 200 OK with Prometheus-formatted text aggregated from all registered metric providers.

  • Error response: 200 OK with # Metrics unavailable if an exception occurs while collecting samples.

  • Side effects: None; the endpoint is read-only but can be polled frequently for monitoring dashboards.

The exporter surfaces operational health data for the reader and every registered integration service. Metric names are generated by concatenating the provider’s .NET type with the original key reported by that provider, lower-casing the result, and replacing any non-alphanumeric characters with underscores. For example, MetricsMonitoringService contributes samples such as metricsmonitoringservice_system_cpu_usage____, and the TCP socket provider publishes entries like tcpsocketservice_connected_clients. Boolean values are normalised to 0 or 1 so they can be scraped as numeric gauges by Prometheus-compatible collectors.

Example scrape showing gauges from each provider:

Refer to the forthcoming observability playbook (tracked in documentation-gap-analysis.md) for guidance on interpreting each provider’s gauges and mapping them to operational alerts.

Debug Routes

Lists all registered API routes (useful for troubleshooting).

  • Success response: 200 OK with an array of { "displayName": "...", "routePattern": "..." } describing every endpoint registered in ASP.NET Core.

  • Side effects: None; the route simply enumerates endpoint metadata for debugging.

External Integration

Test Bearer Token

Performs a credential exchange against an external OAuth/token endpoint using the supplied BearerDTO payload.

  • Success response: 200 OK with the raw token string (or empty string if the remote service omits a token property).

  • Error response: 400 Bad Request with an empty body when the HTTP exchange fails or throws an exception.

  • Side effects: Issues an outbound HTTPS POST (with certificate validation disabled) to the configured URL and logs the result for auditing.

Product GTIN Lookup

  • Success response: 200 OK with the catalog JSON returned by the upstream service when enableExternalApiVerification == "1"; otherwise the controller returns an empty string.

  • Error response: Propagates the upstream HTTP status code (for example 404, 409, 502) along with the body content.

  • Side effects: Every call records an ExternalApiCallEvent in the event queue, capturing payloads, URLs, and responses for downstream telemetry.

Order Search (POST payload)

  • Success response: 200 OK with the upstream order payload when external verification is enabled; otherwise "External Integration Disabled." is returned.

  • Error response: Mirrors the upstream HTTP status code and body content.

  • Side effects: Logs and enqueues an event detailing the outbound request/response, aiding traceability.

Order Lookup by Code

  • Success response: 200 OK with the order JSON from the upstream API when enabled; otherwise an empty string is returned.

  • Error response: Forwards the remote status code and content body.

  • Side effects: Same telemetry event publishing as other external calls.

Publish External Payload (POST)

  • Success response: 200 OK with the upstream response body, or { "message": "Published" } when the remote service returns 204 No Content. If integration is disabled the reader returns an empty string.

  • Error response: Propagated upstream status code/body (for example 400 validation errors).

  • Side effects: Logs and enqueues an external-call event including the remote URL, payload, and response metadata.

Publish External Payload (PUT)

  • Success response: 200 OK with upstream content or { "message": "Published" } on 204 No Content. Disabled integrations return an empty string.

  • Error response: Mirrors the upstream HTTP status code and response text.

  • Side effects: Adds an external call event for monitoring and auditing just like the POST variant.

Reader Mode Control

Set Reader Mode

Changes the active operating mode of the reader. The request body must contain a JSON payload that identifies the desired mode:

Accepted values for mode align with the reader's firmware capabilities. When the request is accepted, the service enqueues a MODE_COMMAND entry for the connected reader. This follows the same internal command queue that powers the MQTT /command/mode workflow, allowing deployments that already automate mode changes over MQTT to reuse the same processing pipeline through the REST API.

MQTT Management

Configure MQTT

Manages MQTT broker configuration and connection settings.

MQTT Command Control

Sends control commands via MQTT.

MQTT Management Commands

Sends management commands via MQTT.

MQTT Mode Commands

Sends mode control commands via MQTT.

Certificate Management

Upload CA Certificate

Uploads a CA certificate for MQTT SSL/TLS connection.

  • Upload constraints:

    • File validation: Requests must include a file whose size does not exceed the configured UploadLimits:MaxFileSizeBytes value. Missing files or files that exceed the limit return 400 Bad Request with a validation message explaining the problem.

    • Retention: The reader keeps at most the number of files defined by UploadLimits:MaxFilesPerDirectory for each endpoint. When a new upload would exceed that count, the oldest file is deleted first-in-first-out.

    • Failure handling: IO or storage errors surface as 500 Internal Server Error.

    • Configuration: Administrators can tune the UploadLimits block (for example in customsettings.json or the deployed appsettings.*.json) to raise or lower both the size (MaxFileSizeBytes) and retention (MaxFilesPerDirectory) limits. The factory configuration sets these to 5 MB and five files respectively, but any restart with new values applies the updated limits.

See also: Upload limit configuration overrides for step-by-step instructions on editing UploadLimits:MaxFileSizeBytes and UploadLimits:MaxFilesPerDirectory in appsettings.json or /customer/appsettings.json before retrying the upload.

Upload Client Certificate

Uploads a client certificate for MQTT SSL/TLS connection.

  • Upload constraints:

    • File validation: Requests must include a file that satisfies the UploadLimits:MaxFileSizeBytes limit; violations return 400 Bad Request with the validation feedback.

    • Retention: Upload pruning follows the configured UploadLimits:MaxFilesPerDirectory cap, removing the oldest file when a new one would exceed it.

    • Failure handling: IO exceptions during upload return 500 Internal Server Error.

    • Configuration: Override UploadLimits settings in deployment configuration to adjust the defaults before restarting the service.

    • Form requirements: Submit both the certificate file and a password form field. Provide an empty string (password=) only when the PFX is not password protected—omitting the field leaves the previous password in place and will cause MQTT mutual TLS failures during the next connection attempt.

The reader stores the uploaded password alongside the certificate (mqttSslClientCertificatePassword) so that future MQTT TLS handshakes can decrypt the private key. Always set the password explicitly—even if unchanged—to avoid connection issues immediately after upload.

Upload HTTP Client Certificate

Uploads a client certificate for HTTP mutual TLS connections.

  • Upload constraints:

    • File validation: The controller requires a file within the UploadLimits:MaxFileSizeBytes limit and returns 400 Bad Request with a descriptive message when validation fails.

    • Retention: The number of stored files is bounded by UploadLimits:MaxFilesPerDirectory, with FIFO pruning when the threshold is exceeded.

    • Failure handling: IO issues encountered during upload trigger 500 Internal Server Error responses.

    • Configuration: Customize the limit values through the UploadLimits configuration (for example in customsettings.json) to suit your deployment.

    • Form requirements: Include both the certificate file and a password form value. Use an explicit empty value only for passwordless PFX bundles; otherwise the prior password remains active and HTTP mTLS requests will be rejected once the new certificate is in place.

The HTTP password is persisted with the certificate (httpClientCertificatePassword) so outbound HTTPS calls can present the client identity. Always set the field intentionally to prevent lingering credentials from breaking connectivity after deployment.

Troubleshooting

  • Upload rejected immediately? Review the 400 Bad Request response for the validation message (typically missing file or limit exceeded) and adjust the upload or configuration accordingly.

  • Expecting older certificates but they are missing? Check the UploadLimits:MaxFilesPerDirectory value; the reader prunes the oldest entries when the retention cap is exceeded.

  • Repeated pruning events can indicate automated upload jobs. Audit scheduling to ensure only required certificates are pushed to the device.

Logging Control

Get Current Log Level

Retrieves the current logging level.

Set Log Level

Updates the logging level.

Request body:

Log Directory Quota Monitoring

SmartReader runs a background quota monitor that watches the /customer/wwwroot/logs directory and raises a warning when the aggregate size of retained log files grows beyond the configured allowance. The quota is computed as FileSizeLimitBytes × RetainedFileCountLimit, and the monitor evaluates the directory on the schedule defined by QuotaCheckIntervalMinutes. When the directory size exceeds the calculated quota, the service emits a warning entry so administrators can archive or delete logs before storage fills.

Default thresholds

  • FileSizeLimitBytes: 102400 bytes (100 KB per log file)

  • RetainedFileCountLimit: 1 retained file (resulting in a 100 KB effective quota by default)

  • QuotaCheckIntervalMinutes: 5 minutes between directory size checks

Configuration

Adjust the thresholds in the LogFileOptions section of appsettings.json (or the environment-specific appsettings.<Environment>.json that your deployment uses). Changes take effect after the reader reloads configuration.

Data Types

StandaloneConfigDTO

Comprehensive configuration object containing all reader settings. Key properties include:

  • Reader identification and network settings

  • Antenna configuration

  • Trigger settings

  • Filter configuration

  • MQTT settings

  • External API integration settings

  • GPIO configuration

  • Logging and debugging options

BearerDTO

Authentication token configuration containing:

  • httpAuthenticationTokenApiUrl: URL for token authentication

  • httpAuthenticationTokenApiBody: Request body for authentication

  • httpAuthenticationTokenApiValue: Token value

LogLevelRequest

Logging level configuration containing:

  • level: Desired logging level (DEBUG|INFORMATION|WARNING|ERROR)

Error Handling

API responses use standard HTTP status codes:

  • 200: Success

  • 400: Bad Request

  • 401: Unauthorized

  • 404: Not Found

  • 500: Internal Server Error

Error responses include a message describing the error condition.

Security Considerations

  1. All endpoints require Basic Authentication

  2. HTTPS is used for all communications

  3. Sensitive operations should be restricted to authorized users

  4. Certificate validation for MQTT SSL/TLS connections

  5. Proper handling of authentication tokens and credentials

Rate Limiting

No specific rate limiting is implemented, but clients should implement reasonable delays between requests to avoid overwhelming the reader.

Best Practices

  1. Always verify SSL/TLS certificates in production

  2. Implement proper error handling in clients

  3. Use appropriate logging levels for different environments

  4. Regularly back up reader configuration

  5. Monitor reader status and implement health checks

  6. Clean up resources (files, connections) when no longer needed

PreviousAdminNextUsing the Smartreader Embedded

Last updated