EasyPro 驱动开发指南

[INFO] 🎉 我的第一个驱动，初始化成功！
[INFO] 📞 收到平台客户端
[INFO] 📊 hello 驱动定时任务执行中...    ← 每 4 秒出现一次
[INFO] 📊 hello 驱动定时任务执行中...
[INFO] 📊 hello 驱动定时任务执行中...

com.sctech.opti.cloud.drivers.inline.ycbox.access.YcboxDriverAccess
com.sctech.opti.cloud.drivers.inline.rcp.access.RcpDriverAccess
com.sctech.opti.cloud.drivers.inline.modbus.access.ModbusAccess
com.sctech.opti.cloud.drivers.inline.secp.access.SecpAccess
com.sctech.opti.cloud.drivers.inline.knx.access.KnxAccess
com.sctech.opti.cloud.drivers.inline.mqtt.access.MqttDriverAccess
com.sctech.opti.cloud.drivers.inline.bacnetip.access.BacnetIpAccess

public interface HttpApiCallBack {

    /*
     * 返回 API 的映射路径
     * 比如返回 "importDriverInstance"
     * 最终 URL 会是 /driver/{driverName}/importDriverInstance
     */
    String getApiMapping();

    /*
     * 执行 API 请求
     * @param param 请求参数 Map（所有查询参数）
     * @param file   上传的文件（可能为 null）
     * @return DriverApiResult 封装执行结果
     */
    DriverApiResult execute(Map<String,String> param, File file);
}

@Slf4j
public class ImportDriverInstanceApi implements HttpApiCallBack {

    @Override
    public String getApiMapping() {
        return "importDriverInstance";  // URL 路径名
    }

    @Override
    public DriverApiResult execute(Map<String,String> param, File file) {
        if (file == null) {
            throw new IllegalArgumentException("配置文件不能为空");
        }
        Long driverId = Long.parseLong(param.get("driverId"));
        // ... 解析 file、导入配置的具体逻辑
        DriverApiResult r = new DriverApiResult();
        r.setData("导入成功");
        return r;
    }
}

@Override
public List<HttpApiCallBack> getHttpApiCallBackList() {
    return List.of(new ImportDriverInstanceApi());
}

public interface ScheduleCallback {
    String getTaskName();          // 任务名（驱动内唯一，不能重复）
    String getCronExpression();   // Cron 表达式：多久执行一次
    String getTaskDescription(); // 任务描述（给人看的）
    void execute();              // 真正要干的活
}

@Slf4j
public class AliveTask implements ScheduleCallback {

    private static final PlatformClient platformClient = RcpDriverAccess.getPlatformClient();

    @Override
    public String getTaskName() { return "aliveTask"; }

    @Override
    public String getCronExpression() { return "0/4 * * * * ?"; }  // 每 4 秒

    @Override
    public String getTaskDescription() { "rcp 驱动实例心跳检测"; }

    @Override
    public void execute() {
        log.debug("心跳检测开始");
        RcpConnectorManager.checkDriverInstanceAlive();
        log.debug("心跳检测完成");
    }
}

// 获取驱动实例
DriverInstance instance = platformClient.getDriverInstance(instanceId);

// 推送点位值到平台（最核心的调用）
platformClient.pushPointValue(pointList);

// 用平台线程池跑异步任务（千万别自己 new Thread）
platformClient.getDriverThreadPoolExecutor().execute(() -> {
    // 异步处理逻辑
});

@Data
public class DriverInstance {
    private Long instanceId;          // 实例 ID（主键）
    private Long driverId;            // 驱动 ID
    private String driverName;        // 驱动名称（要和 getDriverName() 一致）
    private String instanceName;      // 实例名称
    private String instanceDesc;      // 实例描述
    private boolean switchOn;        // 是否启用
    private Integer instanceStatus;   // 实例状态
    private List<DriverInstanceAttr> driverInstanceAttrs;  // 实例属性（配置项）
    private String projectId;         // 项目 ID
    private Long defaultSubsystemId;  // 默认子系统 ID
}

@Data
public class Point {
    // —— 基础标识 ——
    private Long id;                   // 主键 ID
    private String pointName;        // 点位名称
    private String pointUniqueCode;    // 点位唯一码
    private String accessMode;        // 点位地址（如 Modbus 寄存器地址）
    private String dataType;          // 数据类型

    // —— 归属关系 ——
    private Long driverId;
    private Long driverInstanceId;
    private String driverInstanceName;
    private String driverName;
    private String projectId;

    // —— 运行时数据（上报时填）——
    private Object curValue;          // 当前值（上报时填这个）
    private Integer statusFlag;       // 质量码（正常数据设 1，见下方说明）

    // —— 物模型规格（spec）——
    private String dataSpecUnit;      // 单位标识
    private String dataSpecUnitName;  // 单位名称
    private Double optionMin;         // 取值下限
    private Double optionMax;         // 取值上限
    private Double dataSpecStep;      // 步长
    private String dataSpecZero;      // 关闭/0 值语义
    private String dataSpecOne;       // 开启/1 值语义

    // —— 其他 ——
    private Integer sort;             // 排序
    private String pointDescription;  // 描述
    private List<PointAttr> pointAttrs;  // 点位属性
}

@Data
@Accessors(chain = true)
public class DriverApiResult {
    private Boolean success = true;  // 是否成功
    private String errorMsg;        // 错误信息（success=false 时有效）
    private String msg;             // 提示信息
    private Object data;            // 返回数据
}

@Data
public class DriverInstanceAttr {
    private String attrName;     // 属性名（如 "host"），对应SQL里的 attr_name
    private String attrValue;    // 属性值（如 "192.168.1.100"）
    private Long instanceId;   // 所属实例 ID
}

@Data
public class PointAttr {
    private String attrDisplayName;  // 显示名称（给前端用）
    private String attrName;        // 属性名（如 "functionCode"）
    private String attrValue;       // 属性值（如 "3" = 读保持寄存器）
    private Integer attrSort;      // 排序
    private String dataType;        // 数据类型
    private String optionElementType; // 前端控件类型(input/select)
    // ... pointId、driverId、createTime 等
}

com.sctech.opti.cloud.drivers.inline.<driver-name>/
├── access/           # 驱动接入层（实现 DriverAccess，第 3 章讲的）
├── base/             # 基础管理类（连接管理、资源管理，如 XxxConnectorManager）
├── constant/         # 常量定义
├── entity/           # 实体类（驱动特定的数据结构）
├── task/             # 定时任务实现（第 4.2 节，如 AliveTask）
├── api/              # HTTP 接口实现（第 4.1 节，可选，如 ImportDriverInstanceApi）
├── util/             # 工具类
└── server/           # 服务端处理（连接、协议解析，如果是服务端模式）

<dependencies>
    <!-- 驱动 SDK 无需声明，已在主工程内 -->

    <!-- 协议相关依赖（按你的协议按需添加，例如 Netty） -->
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-all</artifactId>
        <version>4.1.x</version>
    </dependency>

    <!-- Lombok（必需） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

@Override
public boolean openDriverInstance(DriverInstance inst) {
    // 实例「开门营业」：建立连接、启动轮询
    return RcpConnectorManager.handleDriverInstanceOpen(inst);
}

@Override
public boolean closeDriverInstance(DriverInstance inst) {
    // 实例「打烊」：关闭连接、释放资源
    return RcpConnectorManager.handleDriverInstanceClose(inst.getInstanceId());
}

@Override
public boolean driverInstanceHasDeleted(Long instanceId) {
    // 实例被删除：彻底清理连接等资源
    return RcpConnectorManager.handleDriverInstanceHasDeleted(instanceId);
}

@Override
public boolean newDriverInstanceHasSaved(DriverInstance inst) {
    // 新实例刚保存：可做初始化（不需要则 return false）
    return false;
}

@Override
public boolean driverInstanceHasUpdated(DriverInstance inst) {
    // 实例配置被修改：可重新加载（不需要则 return false）
    return false;
}

@Override
public void issuePointValueBatch(List<Point> pointList) {
    // 平台下发指令：把点位值写到设备
    RcpConnectorManager.writeAllPointValue(pointList);
}

// 在 openDriverInstance 等方法里，从实例上读取配置
@Override
public boolean openDriverInstance(DriverInstance inst) {
    List<DriverInstanceAttr> attrs = inst.getDriverInstanceAttrs();

    // 方式一：逐个按 attrName 取值（最常用）
    String host = attrs.stream()
        .filter(a -> a.getAttrName().equals("host"))
        .findFirst().map(DriverInstanceAttr::getAttrValue).orElse(null);
    String port = attrs.stream()
        .filter(a -> a.getAttrName().equals("port"))
        .findFirst().map(DriverInstanceAttr::getAttrValue).orElse(null);

    // 方式二：一次性转成 Map，后续直接 get（配置项多时更清爽）
    Map<String, String> cfg = attrs.stream()
        .collect(Collectors.toMap(
            DriverInstanceAttr::getAttrName,
            DriverInstanceAttr::getAttrValue));
    String slaveId = cfg.get("slaveId");

    // 拿到配置后，建立连接等业务逻辑
    return doConnect(host, Integer.parseInt(port), Integer.parseInt(slaveId));
}

// 单条校验：保存单个实例/点位时调用
@Override
public void validateDriverInstanceAttr(List<DriverInstanceAttr> attrList,
        Long instanceId, String projectId) throws Exception {
    // 校验实例属性，比如 IP 格式、端口范围等，不合法就抛异常
    RcpConnectorManager.validateDriverInstanceAttr(attrList, instanceId, projectId);
}

@Override
public void validateDriverPointAttr(List<PointAttr> pointAttrList,
        Long instanceId, Long pointId, String projectId) {
    // 校验点位属性，比如寄存器地址是否合法
}

// 批量校验：导入工程文件（含多个实例/点位）时调用，结果填入 ImportResult
@Override
public void validateDriverInstanceAttrBatch(List<ImportInstanceResultVo> instanceList,
        ImportResult<Object> res) {
    RcpConnectorManager.validateDriverInstanceAttrBatch(instanceList, res);
}

@Override
public void validateDriverPointAttrBatch(List<ImportPointResultVo.ImportPoint> pointList,
        ImportResult<Object> res, Long instanceId, String projectId) throws Exception {
    // 批量校验导入的点位
}

-- 1. 遍历所有项目，为每个项目插入驱动记录
CREATE PROCEDURE proc_insert_xxx_driver()
BEGIN
    DECLARE v_project_id, v_driver_id ...;
    DECLARE cur CURSOR FOR SELECT id FROM `ibms-system`.sys_project;

    OPEN cur;
    read_loop: LOOP
        FETCH cur INTO v_project_id;

        -- 2. 幂等保护：该项目下已有此驱动则跳过
        IF NOT EXISTS (SELECT 1 FROM iot_driver
            WHERE driver_name='xxx' AND project_id=v_project_id) THEN

            -- 3. 插入 iot_driver（驱动主记录 + 权限开关）
            INSERT INTO iot_driver(driver_name, driver_version, ..., project_id)
            VALUES('xxx', 'v 1.0.0', ..., v_project_id);
            SET v_driver_id = LAST_INSERT_ID();  -- 拿到刚插入的driver_id

            -- 4. 插入 iot_driver_attribute（实例属性，如 host/port/slaveId）
            --    attr_name 要和代码里 getDriverInstanceAttrs 读取的 key 一致！
            INSERT INTO iot_driver_attribute
                (driver_id, attr_display_name, attr_name, data_type,
                 option_check_type, option_required, option_max, option_min, ...)
            VALUES
                (v_driver_id, 'IP地址',   'host',    'string', 'ip',   1, NULL, NULL, ...),
                (v_driver_id, '端口',     'port',    'int',    'port', 1, 65535, 1,    ...),
                (v_driver_id, '从站号',   'slaveId', 'int',    'int',  1, 247,   1,    ...);

            -- 5. 插入 iot_driver_point_attribute（点位属性，如寄存器地址、功能码）
            INSERT INTO iot_driver_point_attribute
                (attr_display_name, attr_name, data_type, driver_id, ...) VALUES (...);
        END IF;
    END LOOP;
    CLOSE cur;
END

-- 执行后清理
CALL proc_insert_xxx_driver();
DROP PROCEDURE IF EXISTS proc_insert_xxx_driver;

// 连接管理器示例：用 ConcurrentHashMap 保证线程安全
// 注意：这是驱动的普通工具类，不要加 @Component 等 Spring 注解
// 驱动自己 new 出来用（如 static 实例），靠 SPI 加载而非 Spring 容器
public class ConnectionManager {
    private static final ConnectionManager INSTANCE = new ConnectionManager();
    public static ConnectionManager getInstance() { return INSTANCE; }

    private final ConcurrentHashMap<Long, Connection> connections = new ConcurrentHashMap<>();

    public Connection getConnection(Long instanceId) {
        return connections.get(instanceId);
    }

    public void removeConnection(Long instanceId) {
        Connection conn = connections.remove(instanceId);
        if (conn != null) conn.close();
    }
}

@Override
public void execute() {
    log.debug("心跳检测开始");
    try {
        // 通过 PlatformClient 获取当前驱动的全部实例
        List<DriverData> driverDataList = platformClient.getDriverData();
        List<InstanceStatusToPush> statusList = new ArrayList<>();

        for (DriverData data : driverDataList) {
            for (DriverInstance inst : data.getInstances()) {
                // 检查该实例连接是否健康（各驱动自己实现）
                DriverInstanceStatus status = checkConnectionAlive(inst);
                InstanceStatusToPush s = new InstanceStatusToPush();
                s.setInstanceId(inst.getInstanceId());
                s.setStatus(status);
                statusList.add(s);
            }
        }
        if (!statusList.isEmpty()) {
            platformClient.pushInstanceKeepAlive(statusList);
        }
    } catch (Exception e) {
        log.error("心跳检测失败", e);
    }
}