Skip to content
←Back to Open Source

OPEN SOURCE DEEP DIVE

OpenTCSAGVJavaUDP

A Community openTCS Driver for Kecong UDP Controllers

A community openTCS communication adapter for Kecong MRC/FRC controllers over UDP protocol V2.0, with an evidence-led review of its navigation path, initialization risks, and unverified relationship to commercial JRC3000 systems.

What This Project Is, and What It Is Not

This repository is a community-built openTCS communication adapter for Kecong MRC and FRC series AGV controllers. It translates movement commands from openTCS into Kecong UDP protocol V2.0 frames, then reports position, task state, and battery information back to the openTCS vehicle process model. The code targets Java 11 and identifies openTCS 7.2.1 as its tested platform.

The scope boundary matters. This is not a JRC3000 driver. JRC3000 is a closed commercial system, and the repository provides no evidence that the two products share code, remain protocol-compatible, or were connected through reverse engineering. Claims about JRC3000 support should be avoided unless the vendor supplies direct evidence. The repository is also archived, so it is best treated as a field-note-grade protocol reference rather than an actively maintained production package.

Licensing is unresolved. The README says MIT, but the repository contains no LICENSE file and GitHub does not identify a license. A sentence in the README is not enough to establish redistribution rights. Commercial adopters should obtain written clarification from the author before relying on the code.

Where the Adapter Sits

openTCS handles transport orders, routing, and fleet-level dispatch. A communication adapter translates abstract movement commands into controller-specific operations and reports equipment state back to the kernel. In this project, a factory reads vehicle properties and creates an adapter. The adapter keeps one sent command, polls the controller, and advances the command when the reported navigation task reaches a terminal state.

The codebase has two Maven modules. The protocol module owns the frame codec, UDP channel, command encoders, response decoders, and data models without depending on openTCS. The adapter module implements the openTCS vehicle communication interface and maps Kecong state into the openTCS process model. That separation is useful: developers can test or reuse the protocol library independently from the dispatch stack.

The UDP Frame Model

A frame starts with a 16-byte authorization code followed by the protocol version, message type, a 16-bit sequence number, a fixed service code, command code, execution code, length field, and payload. The 28-byte header uses little-endian fields, and the payload is capped at 512 bytes. Each request increments a shared sequence counter, and a lock serializes the send and receive operation on each socket.

The default navigation endpoint is 192.168.100.178:17804. The QR and variable endpoint is 192.168.100.200:17800. The documented polling interval is 100 milliseconds. Navigation uses a socket timeout of at least two seconds, while the variable channel defaults to one second. Separate sockets are created for the navigation and QR-side paths.

The protocol package includes many more commands than the adapter actually uses. It contains models or codecs for hybrid navigation, status subscription, immediate actions, cargo state, multi-variable access, traffic coordination, QR navigation, and magnetic navigation. Those artifacts prove that protocol work was started; they do not prove that the live adapter exercises each feature.

The Live Control Path

The main status request is 0x17. Its decoded response contains double-precision position and heading, battery ratio, operating mode, navigation task state, localization state, and confidence. The adapter polls it approximately every 100 milliseconds and updates the openTCS pose, vehicle state, and Kecong-specific properties.

Navigation uses a 0x16 request with a fixed 432-byte payload. The destination point ID occupies bytes 4 through 11, the operation code is set to zero for immediate execution, the navigation mode targets a map point, and traffic coordination is disabled. Point mapping prefers the kc:markerId property and falls back to the openTCS point name. A deployment should therefore use the controller's numeric map ID as the point name or configure the property consistently.

Fork actions use a 0x00 variable write on the QR port. LOAD and PICKUP set Forkup, UNLOAD and DROPOFF set Forkdown, and the implementation also names Forkforward and Forkback. The selected variable is held at one for five seconds, written back to zero, and then assumed complete after another two seconds. Three failed stop attempts do not block task completion, and a 30-second timeout prevents the command from hanging forever. The timeout is a liveness mechanism, not proof that the mechanical action reached the requested position.

Battery level normally comes directly from the 0x17 response. Optional 0x01 and 0x02 paths can read one variable or several variable members, and the multi-variable format includes corrections made from tests on a real MRC controller. These are optional configurations rather than the default live status path.

Documented Surface Versus Runtime Coverage

The README marks 0xAE hybrid navigation, 0xAF status polling, 0xB1 subscriptions, 0xB2 actions, 0xF1 and 0xF5 QR navigation, 0xE0 through 0xE3 magnetic navigation, and 0x70 and 0x71 traffic management as supported. The protocol package does contain corresponding structures or codecs, but the active adapter does not route those features through its command, polling, or failure paths.

The subscription refresh method exists, but no scheduler invokes it and the subscription future is never assigned. Polling remains the real source of state. The transferable process model is empty, canProcess accepts every transport order, and the pause and generic message hooks are no-ops. These are not compile errors. They are mismatches between the capability surface implied by the documentation and the behavior implemented by the live driver.

Initialization and Physical Safety

Automatic initialization is disabled by default in the factory. When enabled, the adapter retries 0x17 up to five times to obtain the current pose. It then switches to manual mode, sends a 0x14 manual-position command, sends 0x1F to confirm that position, and switches back to automatic mode after fixed short sleeps.

The README describes a longer wait that polls localization to completion. The implementation does not perform that loop. It also does not stop the sequence when the mode-switch or confirmation request returns a failed execution code. A controller in an unexpected pose, an incomplete localization, or a dropped UDP response can therefore be followed by another state-changing request.

This sequence should be tested on an isolated controller or an empty vehicle. A safer implementation would model initialization as an observable state machine: require the correct response for every transition, verify localization reaches the expected state, and block automatic mode on any timeout or ambiguity. No live AGV with a payload should be used for first-contact testing.

Task Completion and Failure Semantics

The 0x17 navigation state distinguishes waiting, moving, paused, done, and failed. The state translator maps moving to openTCS executing and failure to error. However, done and failed enter the same command-completion branch. Both consume the sent movement command and call commandExecuted. openTCS may show the vehicle as failed, but the adapter does not give the kernel a clean per-command failure result.

Polling input and output exceptions are swallowed. The 0x17 decoder does not populate the abnormal-event list, so the documented error-event reporting path is not demonstrated by the active poll loop. The process model exposes a setter for error codes, but the live path never calls it.

The UDP channel returns the first datagram that decodes successfully. It checks the execution code, but it does not correlate the authorization code, sequence number, command code, or source address with the request. That may work on a dedicated point-to-point network, but delayed or injected datagrams on a shared industrial network can be mistaken for the current response. A production driver should reject stale and mismatched packets before updating vehicle state.

Configuration and Secret Handling

Vehicle properties override navigation and QR endpoints, ports, polling interval, authorization code, automatic initialization, and energy source. When no authorization code is supplied, a built-in value is used. The constructor logs the full effective authorization code, and the factory logs a configured code as part of the source description. Logging access material at normal level is unsuitable for unattended production deployment.

The README and implementation also disagree on point mapping. The documentation recommends kecong:pointId, while the navigation code reads kc:markerId before falling back to the point name. A site that follows the README but uses display names can send the wrong identifier to the controller. Numeric controller IDs as point names are the simplest safe convention until the property mismatch is fixed.

Deployment uses two JARs, one for the protocol module and one for the adapter. The project states Java 11 or newer, Maven 3.6 or newer, openTCS 7.x, and minimum Kecong navigation and firmware versions. Those compatibility claims still need to be matched against the exact controller release used on site.

Tests, Releases, and Maintenance

For commit 82c7cfc, the Java CI workflow runs only the protocol module tests across Java 11, 17, and 21. Those jobs pass and enforce an 85 percent coverage threshold for the protocol module. This is useful evidence for frame encoding and little-endian parsing. It is not evidence that the adapter, a real UDP peer, or a vehicle has equivalent regression coverage. Adapter tests exist in the repository but are outside the current CI command.

The release workflow skips tests and installs only openTCS api-base before packaging. The adapter also depends on opentcs-api-injection. This is a concrete release risk that should be reproduced in an isolated environment before relying on a tag artifact.

At review time the repository was archived, with one star, zero forks, and eleven open issues. Its last commit was on July 22, 2026, and it contains no image assets or license file. Archived status means users should not assume upstream fixes for protocol concurrency, authentication, or command semantics.

Recommended Use

The project is valuable as a compact, readable sample of Kecong UDP V2.0 integration. The frame structure is explicit, the navigation and variable paths are short, and the protocol module is independent from openTCS. It is suitable for protocol inspection, bench integration, and building a more complete internal driver.

It does not yet carry enough evidence for direct unattended operation. A serious deployment should separate command completion from command failure, correlate UDP responses by request and sender, implement and monitor localization transitions, expose equipment errors, narrow the unconditional canProcess response, test the adapter in CI, remove credentials from logs, and resolve licensing.

For a one-off lab connection to a Kecong MRC or FRC controller, this repository can shorten protocol discovery. For a production fleet, use it as a reference and build or fork a driver with explicit failure semantics and site-validated safety behavior. None of these conclusions imply support for, compatibility with, or reverse engineering of the closed JRC3000 product.

As an Amazon Associate, we earn from qualifying purchases.