If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/IoT-Technology/IoT-Technical-Guide shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 3 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live IoT-Technology/IoT-Technical-Guide repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/IoT-Technology/IoT-Technical-Guide.

What it runs against: a local clone of IoT-Technology/IoT-Technical-Guide — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in IoT-Technology/IoT-Technical-Guide | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1006 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of IoT-Technology/IoT-Technical-Guide. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/IoT-Technology/IoT-Technical-Guide.git
#   cd IoT-Technical-Guide
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of IoT-Technology/IoT-Technical-Guide and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "IoT-Technology/IoT-Technical-Guide(\\.git)?\\b" \\
  && ok "origin remote is IoT-Technology/IoT-Technical-Guide" \\
  || miss "origin remote is not IoT-Technology/IoT-Technical-Guide (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "IOT-Guide-Actor/src/main/java/iot/technology/actor/core/Actor.java" \\
  && ok "IOT-Guide-Actor/src/main/java/iot/technology/actor/core/Actor.java" \\
  || miss "missing critical file: IOT-Guide-Actor/src/main/java/iot/technology/actor/core/Actor.java"
test -f "IOT-Guide-Actor/src/main/java/iot/technology/actor/DefaultActorSystem.java" \\
  && ok "IOT-Guide-Actor/src/main/java/iot/technology/actor/DefaultActorSystem.java" \\
  || miss "missing critical file: IOT-Guide-Actor/src/main/java/iot/technology/actor/DefaultActorSystem.java"
test -f "IOT-Guide-Actor/src/main/java/iot/technology/actor/core/AbstractActor.java" \\
  && ok "IOT-Guide-Actor/src/main/java/iot/technology/actor/core/AbstractActor.java" \\
  || miss "missing critical file: IOT-Guide-Actor/src/main/java/iot/technology/actor/core/AbstractActor.java"
test -f "IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/PacketCodec.java" \\
  && ok "IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/PacketCodec.java" \\
  || miss "missing critical file: IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/PacketCodec.java"
test -f "IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/CustomProtocolHandler.java" \\
  && ok "IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/CustomProtocolHandler.java" \\
  || miss "missing critical file: IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/CustomProtocolHandler.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1006 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~976d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/IoT-Technology/IoT-Technical-Guide"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

An educational IoT platform framework that builds a high-performance IoT infrastructure from scratch, featuring a custom Actor model implementation (IOT-Guide-Actor) for concurrent message-driven architecture, plus protocol implementations for MQTT, CoAP, BACnet, and Modbus. It includes source code analysis of Thingsboard and demonstrates complete IoT system design patterns including rule engines, device shadows, and thing models. Multi-module Maven monorepo with separate subprojects: IOT-Guide-Actor (custom actor framework core), IOT-Guide-BACnet (BACnet protocol implementation), IOT-Guide-CoAP (CoAP protocol). Core actor system in IOT-Guide-Actor/src/main/java/iot/technology/actor/ with ActorSystem, ActorMailbox, ActorRef implementing message-driven concurrency patterns. Each protocol module is independently buildable.

IoT platform engineers and backend developers who need to understand IoT architecture patterns, protocol implementations, and scalable device communication systems. Contributors are learning-focused developers studying Thingsboard internals and building custom IoT solutions for smart home, industrial, or manufacturing use cases.

Actively developed educational project with Travis CI integration and recent commit history. Lacks comprehensive test coverage (only test stubs visible in IOT-Guide-Actor), so treat as learning resource rather than production framework. Has 1w+ GitHub stars on referenced Thingsboard, but this repo itself is a study guide—use for understanding patterns, not production deployments.

This is an educational codebase with incomplete implementations (test files like FailedToInitActor.java and SlowInitActor.java are minimal stubs). No visible dependency lock files or version constraints documented. Risk of using incomplete actor system or protocol implementations in production. Single-author risk typical of educational repos; focus is on teaching architecture, not battle-tested implementations.

Repository appears to be in long-term maintenance mode (last commit visible in CI badge). Primary activity is documenting IoT patterns and protocol implementations. No active feature branches or PRs visible in file structure. Focus is on providing learning materials and runnable examples rather than rapid development.

Clone and build with Maven: git clone https://github.com/IoT-Technology/IOT-Technical-Guide.git && cd IOT-Technical-Guide && mvn clean install. Individual modules can be built separately: mvn -pl IOT-Guide-Actor clean install. Java 8+ required (see maven.compiler.source/target in pom.xml).

Daily commands: Build first: mvn clean install. Tests run via mvn test (in IOT-Guide-Actor). No explicit dev server—this is a framework library. To use: include IOT-Guide-Actor JAR in your IoT project and instantiate DefaultActorSystem via ActorCreator API. See IOT-Guide-Actor/src/test/java/iot/technology/actor/ActorSystemTest.java for usage examples.

• IOT-Guide-Actor/src/main/java/iot/technology/actor/core/Actor.java — Core actor interface defining the fundamental contract for all actor implementations in this distributed messaging system.
• IOT-Guide-Actor/src/main/java/iot/technology/actor/DefaultActorSystem.java — Default actor system implementation managing actor lifecycle, dispatcher, and message routing—the backbone of concurrent message processing.
• IOT-Guide-Actor/src/main/java/iot/technology/actor/core/AbstractActor.java — Base actor class providing lifecycle hooks (init, receive, destroy) that all custom actors must extend.
• IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/PacketCodec.java — Packet codec interface for encoding/decoding custom protocol messages—essential for protocol serialization.
• IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/CustomProtocolHandler.java — Main Netty handler for custom protocol message processing and routing in the server pipeline.
• IOT-Guide-Actor/src/main/java/iot/technology/actor/core/ActorMailbox.java — Message queue implementation for actor message delivery—critical for ensuring FIFO message ordering per actor.
• IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/client/CustomProtocolClient.java — Client-side implementation demonstrating how to connect and communicate via custom protocol.

Add a new Actor type

1. Create a new class extending AbstractActor in your module under iot/technology/actor/ (IOT-Guide-Actor/src/main/java/iot/technology/actor/core/AbstractActor.java)
2. Implement the onReceive() method to handle ActorMsg types, and optional init()/destroy() lifecycle hooks (IOT-Guide-Actor/src/main/java/iot/technology/actor/core/Actor.java)
3. Register your actor with DefaultActorSystem via getActorRef() or create methods (IOT-Guide-Actor/src/main/java/iot/technology/actor/DefaultActorSystem.java)
4. Define custom ActorMsg or IntActorMsg subclasses in iot/technology/actor/message/ for your domain (IOT-Guide-Actor/src/main/java/iot/technology/actor/message/ActorMsg.java)

Add a new custom protocol packet type

1. Create a new request/response packet class extending Packet in iot/technology/custom/protocol/request/ or response/ (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/Packet.java)
2. Define the packet structure with command type and serialization logic (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/protocol/request/LoginRequestPacket.java)
3. Update PacketCodec encode/decode methods to handle your new packet type (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/codec/PacketEncoder.java)
4. Add handler in CustomProtocolHandler.channelRead0() to process the new packet (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/CustomProtocolHandler.java)

Add a new console command for client

1. Create a new class implementing ConsoleCommand interface in iot/technology/custom/client/console/ (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/client/console/ConsoleCommand.java)
2. Implement command() method returning command keyword and execute() method with your logic (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/client/console/LoginConsoleCommand.java)
3. Register your command in ConsoleCommandManager by adding it to the command map (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/client/console/ConsoleCommandManager.java)

Add encryption to custom protocol

1. Create an Encryption implementation class in iot/technology/custom/encryption/impl/ (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/encryption/Encryption.java)
2. Implement encrypt() and decrypt() methods (see Aes128Encryption or NotEncryption as examples) (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/encryption/impl/Aes128Encryption.java)
3. Update PacketCodec to use your encryption in encode/decode pipeline (IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/codec/PacketCodecHandler.java)

• Custom Actor Model (IOT-Guide-Actor) — Provides lightweight, message-

No explicit configuration files (application.properties/yml) visible—configuration likely external or hardcoded in ActorSystemSettings.java. Thread factory (ActorThreadFactory.java) appears custom; behavior under high concurrency untested. Mailbox blocking strategy not documented—may cause deadlocks under specific device patterns. Tests don't compile or run (test files like SlowInitActor.java are mock stubs, not real tests). Parent pom.xml imported but not in file list—build may fail if parent versions undefined. BACnet and CoAP modules incomplete (src/main files missing implementations).

• Actor Model (Message-Driven Concurrency) — IOT-Guide-Actor implements actors as the core abstraction for handling thousands of concurrent IoT devices without shared mutable state or traditional locking—essential for scalable telemetry collection
• MQTT Protocol (v3.1, v3.1.1, v5.0) — Primary publish-subscribe protocol for IoT device communication covered extensively in this guide—asymmetric, lightweight, reliable message delivery with QoS levels critical for battery-powered sensors
• CoAP (Constrained Application Protocol) — Lightweight alternative to MQTT for resource-constrained IoT devices (6LoWPAN networks)—uses UDP instead of TCP, reducing overhead on cellular/mesh networks
• Device Shadow / Digital Twin — Server-side representation of device state allowing offline updates and eventual consistency—referenced in repo description as 'device shadow', critical for handling intermittently connected IoT devices
• Thing Model (Device Capability Modeling) — Schema/contract defining device properties, events, and commands (温model concept)—enables semantic understanding of heterogeneous device types in a unified platform
• Message Backpressure & Mailbox Overflow — ActorMailbox in this implementation must handle spikes from thousands of devices reporting simultaneously—backpressure strategies prevent memory exhaustion but require careful tuning of queue depths and rejection policies
• Protobuf Serialization — Efficient binary serialization format for telemetry messages—IoT platforms use Protobuf instead of JSON to reduce bandwidth on cellular/satellite links where data costs money

• thingsboard/thingsboard — The production IoT platform that this repo explicitly analyzes and learns from—provides reference implementation for device management, telemetry ingestion, and rule engines
• eclipse/paho.mqtt.java — MQTT Java client used by IoT platforms to communicate with brokers—essential dependency for the MQTT protocol features this guide covers
• scalecube/scalecube-cluster — Production-grade actor-based distributed system framework—comparable alternative to IOT-Guide-Actor's custom implementation with battle-tested clustering
• netty/netty — Low-level networking framework used in protocol implementations (MQTT, CoAP, BACnet handlers)—underpins event-driven I/O for thousands of concurrent connections
• alibaba/arthas — Diagnostic tool for Java IoT platforms running in production—useful for debugging actor system behavior and device communication issues in deployed systems

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for ActorSystem with message routing

The IOT-Guide-Actor module has core actor infrastructure (ActorSystem.java, DefaultActorSystem.java, ActorMailbox.java) but ActorSystemTest.java only contains basic tests. Add integration tests covering: multi-actor message passing, actor failure recovery with different InitFailureStrategy and ProcessFailureStrategy implementations, and dispatcher thread pool behavior under load. This is critical for a IoT platform handling concurrent device communications.

• [ ] Create IOT-Guide-Actor/src/test/java/iot/technology/actor/integration/ActorMessageRoutingTest.java to test message delivery across actor hierarchies
• [ ] Create IOT-Guide-Actor/src/test/java/iot/technology/actor/integration/ActorFailureRecoveryTest.java testing both InitFailureStrategy and ProcessFailureStrategy with different actor topologies
• [ ] Create IOT-Guide-Actor/src/test/java/iot/technology/actor/integration/DispatcherLoadTest.java to verify Dispatcher.java handles high-throughput scenarios with ActorThreadFactory.java
• [ ] Add test fixtures in ActorTestCtx.java for common actor creation patterns

Add missing protocol implementation tests for CoAP and Custom-Protocol modules

IOT-Guide-Coap and IOT-Guide-Custom-Protocol modules have resource/server implementations but no visible test directories. For an IoT platform guide, these need test coverage: CoAP resource lifecycle (HelloResource.java, WritableResource.java, RemovableResource.java, TimeResource.java) and custom protocol message encoding/decoding. This validates that code examples are actually functional.

• [ ] Create IOT-Guide-Coap/src/test/java/iot/technology/coap/CoAPResourceLifecycleTest.java testing resource creation, GET/PUT/DELETE handlers for each resource type
• [ ] Create IOT-Guide-Coap/src/test/java/iot/technology/coap/IOTCoapServerIntegrationTest.java with a real CoAP client testing against IOTCoapServer.java
• [ ] Create IOT-Guide-Custom-Protocol/src/test/java/iot/technology/custom/CustomProtocolEncodingTest.java and CustomProtocolDecodingTest.java for message serialization
• [ ] Add README.md files in test directories documenting how to run tests against the protocol servers

Implement GitHub Actions CI workflow for multi-module Maven build and test validation

The repo has .travis.yml for Travis CI but modern practice uses GitHub Actions. Create a workflow that: builds all modules (IOT-Guide-Actor, IOT-Guide-Bacnet, IOT-Guide-Coap, IOT-Guide-Custom-Protocol) with Maven, runs test suites per module, validates coverage for core actor system, and publishes test reports. This ensures contributor PRs don't break the multi-module IoT platform architecture.

• [ ] Create .github/workflows/maven-build.yml with matrix strategy building against Java 8 and Java 11 (specified in pom.xml maven.compiler.target)
• [ ] Add test phase validating all modules: IOT-Guide-Actor, IOT-Guide-Bacnet, IOT-Guide-Coap, IOT-Guide-Custom-Protocol with explicit test goal
• [ ] Configure JUnit report publishing with actions/upload-artifact to preserve test results across runs
• [ ] Add code coverage reporting (jacoco plugin) specifically for IOT-Guide-Actor module as the foundational component

• Implement proper unit tests for IOT-Guide-Actor/src/main/java/iot/technology/actor/core/ActorMailbox.java covering edge cases like queue overflow, message ordering under concurrent sends, and poison pill handling—currently only stubs exist
• Complete BACnet protocol implementation by adding codec and object model handlers to IOT-Guide-Bacnet/src/main/java/iot/technology/bacnet/util/BACnetUtil.java—test file shows read/write operations but implementation is empty
• Add comprehensive documentation with code examples in README for creating custom actors (extending AbstractActor.java) for specific device types like temperature sensors or actuators—critical for onboarding IoT developers

• Medium · Incomplete POM Dependency Declaration — pom.xml (all modules). The provided pom.xml snippet is truncated and incomplete. The junit dependency closing tag is cut off, making it impossible to fully analyze all dependencies for known vulnerabilities. This incomplete configuration could mask security issues. Fix: Provide complete pom.xml files and run 'mvn dependency:check' or use tools like OWASP Dependency-Check to scan for known CVEs in all dependencies.
• Medium · Missing Dependency Version Pinning — IOT-Guide-Actor/pom.xml and other module pom.xml files. The pom.xml shows dependencies without explicit version tags (e.g., slf4j-api, logback-core). They rely on parent POM version management, which could lead to unexpected version updates if parent POM is modified. Fix: Explicitly pin critical dependency versions in each module's pom.xml or use a bill-of-materials (BOM) to centrally manage versions.
• High · Potential Unsafe Actor Message Handling — IOT-Guide-Actor/src/main/java/iot/technology/actor/message/. The codebase includes an Actor system with message passing (ActorMsg, IntActorMsg). Without visible input validation or serialization controls, there's risk of deserialization attacks or unsafe message processing if messages come from untrusted sources. Fix: Implement strict input validation for all incoming messages. Use safe deserialization practices. Consider using allowlists for message types. Review ActorMailbox and message handling for injection vulnerabilities.
• High · Custom Protocol Implementation Without Visible Security Controls — IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/. IOT-Guide-Custom-Protocol module implements a custom protocol with handlers and codecs. Custom protocol implementations are prone to security vulnerabilities if encryption, authentication, and input validation are not properly implemented. Fix: Review CustomProtocolHandler and PacketCodecHandler for proper cryptographic controls, authentication mechanisms, and input validation. Ensure all network inputs are sanitized.
• Medium · Unencrypted CoAP Implementation — IOT-Guide-Coap/src/main/java/iot/technology/coap/. IOT-Guide-Coap module provides CoAP server resources (HelloResource, WritableResource) without visible DTLS/encryption configuration. CoAP without DTLS is vulnerable to eavesdropping and MITM attacks. Fix: Implement DTLS (Datagram TLS) for all CoAP communications. Validate the CoAP library version for known vulnerabilities. Use secure cipher suites.
• Medium · No Visible Authentication in Protocol Implementations — IOT-Guide-Custom-Protocol/src/main/java/iot/technology/custom/client/console/. CustomProtocolClient includes login/logout commands, but the implementation details are not visible. Without proper authentication and session management, these features could be vulnerable to brute force, session hijacking, or authentication bypass. Fix: Implement strong authentication mechanisms (OAuth2, JWT with secure signing). Add rate limiting on login attempts. Use secure session management with proper token expiration.
• Low · Travis CI Configuration Exposed — .travis.yml. .travis.yml file is present but content not provided. Travis CI configuration files can potentially expose sensitive information if not properly configured (e.g., API keys, credentials in build logs). Fix: Review .travis.yml to ensure no secrets are logged. Use encrypted environment variables for sensitive data. Regularly audit CI/CD logs for accidental credential exposure.
• Medium · Test Code in Main Source Directory — IOT-Guide-Bacnet/src/main/java/iot/technology/bacnet/. Files like BacnetYabeReadTest.java and BacnetYabeWriteTest.java appear to be in the main source directory (/src/main) rather than test directory (/src/test), which could accidentally deploy test code to production. Fix: Move all test classes to src/test/java directory. Configure Maven to exclude test classes from production builds. Use separate test profiles.
• Medium · — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.