jt808-server Documentation

For Spring Boot users, the recommended way to integrate is via Maven.

1. Install the jtt808-protocol module to your local Maven repository using mvn install.
2. Add the dependency to your pom.xml:

<dependency>
    <groupId>org.yzh</groupId>
    <artifactId>jtt808-protocol</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

3. Configure the service URL in application.yml:

jt808-service:
  base-url: http://127.0.0.1:8100

4. Use JT808Service to interact with the gateway in your code.

package com.xxx;

import org.yzh.protocol.service.JT808Service;

@Service
public class YourService {

    @Autowired
    private JT808Service jt808Service;

    public void test() {
        JTMessage message = new JTMessage();
        message.setClientId("12345678901");
        try {
            T0001 result = jt808Service.send("8304", message);
            System.out.println(result);
        } catch (WebClientResponseException e) {
            R error = e.getResponseBodyAs(R.class);
            System.out.println(error);
        }
    }
}

The org.yzh.Elucidator tool is a message interpreter used to analyze the mapping between hex strings and Java objects. It helps identify exactly which byte positions correspond to which object properties, making it easier to debug parsing errors.

To use it, extend JT808Beans and use the decode and encode methods provided by the JTMessageAdapter.

package org.yzh;

public class Elucidator extends JT808Beans {

    public static final JTMessageAdapter coder = new JTMessageAdapter("org.yzh.protocol");

    public static void main(String[] args) {
        String hex = "020000d40123456789017fff000004000000080006eeb6ad02633df7013800030063200707192359642f000000400101020a0a02010a1e00640001b2070003640e200707192359000100000061646173200827111111010101652f000000410202020a0000000a1e00c8000516150006c81c20070719235900020000000064736d200827111111020202662900000042031e012c00087a23000a2c2a200707192359000300000074706d732008271111110303030067290000004304041e0190000bde31000d90382007071923590004000000006273642008271111110404049d";
        JTMessage msg = H2019(T0200JSATL12());

        msg = decode(hex);
        hex = encode(msg);
    }
}

You can extend the protocol by defining new message classes using annotations. This replaces manual packet assembly/disassembly with a declarative approach similar to Hibernate.

• @Message(description): Defines the message type (equivalent to @Table).
• @Field(desc, length, ...): Defines a specific property within the message (equivalent to @Column).

package org.yzh.protocol.t808;

@Message(JT808.终端注册)
public class T0100 extends JTMessage {

    @Field(desc = "省域ID")
    private short provinceId;
    @Field(desc = "市县域ID")
    private short cityId;
    @Field(length = 11, desc = "制造商ID")
    private String makerId;
    @Field(length = 30, desc = "终端型号")
    private String deviceModel;
    @Field(length = 30, desc = "终端ID")
    private String deviceId;
    @Field(desc = "车牌颜色：0.未上车牌 1.蓝色 2.黄色 3.黑色 4.白色 9.其他")
    private byte plateColor;
    @Field(desc = "车辆标识")
    private String plateNo;
}

To process messages received from terminals, create an @Endpoint class and use the @Mapping annotation to route specific message types to methods. This is similar to using @Controller and @RequestMapping in Spring MVC.

package org.yzh.web.endpoint;

@Endpoint
public class JT808Endpoint {

    @Autowired
    private DeviceService deviceService;

    @Mapping(types = 0x0100, desc = "终端注册")
    public T8100 register(T0100 message, Session session) {
        T8100 result = new T8100();
        result.setResponseSerialNo(message.getSerialNo());

        DeviceInfo device = deviceService.register(message);
        if (device != null) {
            session.register(message);
            result.setToken("1234567890A");
            result.setResultCode(T8100.Success);
        } else {
            result.setResultCode(T8100.NotFoundTerminal);
        }
        return result;
    }
}