technolife.TC101.Communication 1.0.0

Technolife.Tc101.Communication

TC101 erişim terminalleri için MQTT komut istemcisi, filo yönetimi, SQL komut kuyruğu, cihaz whitelist/blacklist ve isteğe bağlı trafik log kütüphanesi.

• Hedef çerçeve: netstandard2.0 (Net Framework 4.8+, .NET 6/8 WinForms/console ile uyumlu)
• Bağımlılıklar: MQTTnet, Newtonsoft.Json, Microsoft.Data.SqlClient

Host uygulamalar (Workbench, CardBulkLoad, kendi UI’nız) yalnızca bu paketi referans alıp ayar + bağlan + olayları görüntülemelidir. İş kuralları kütüphanede toplanır.

---

İçindekiler

1. Kurulum
2. Hızlı başlangıç
3. Mimari özet
4. Ayarlar
5. Tc101Runtime
6. MQTT oturumu
7. Topic’ler
8. Protokol zarfı ve komutlar
9. Komut gönderme ve kuyruk
10. Cihaz dizini ve erişim (whitelist)
11. EMQX filo kaynağı
12. Trafik log
13. Olaylar (events)
14. SQL şema
15. Gözlemlenebilirlik
16. Host checklist
17. Sınırlar

---

1. Kurulum

Proje referansı

<ItemGroup>
  <ProjectReference Include="..\Technolife.Tc101.Communication\Technolife.Tc101.Communication.csproj" />
</ItemGroup>

Gerekli using’ler

using Technolife.Tc101.Communication;
using Technolife.Tc101.Communication.Configuration;
using Technolife.Tc101.Communication.Devices;
using Technolife.Tc101.Communication.Emqx;
using Technolife.Tc101.Communication.Protocol;
using Technolife.Tc101.Communication.Queue;
using Technolife.Tc101.Communication.Session;
using Technolife.Tc101.Communication.Traffic;

---

2. Hızlı başlangıç

var settings = WorkbenchSettings.LoadOrCreate(); // %AppData%\Technolife\Tc101Mqtt\settings.json

using (var runtime = new Tc101Runtime(
    settings.Broker,
    settings.Protocol,
    settings.Queue,
    settings.Emqx,
    log: null,
    settings.DeviceAccess,
    settings.TrafficLog))
{
    await runtime.EnsureReadyAsync();          // SQL şema + access listeleri
    await runtime.Device.ConnectAsync();       // MQTT

    // Cihazları gör (EMQX + MQTT Up)
    var devices = await runtime.DeviceDirectory.RefreshFromEmqxAsync();

    // Boş whitelist = kimse işlenmez. İşlenecek MAC’i ekleyin:
    var mac = "0c:dc:7e:36:c0:9f";
    await runtime.DeviceDirectory.SetWhitelistAsync(mac);

    // Komut gönder (offline + queueable ise SQL kuyruğa düşer)
    var json = runtime.Device.Commands.GetStatus().ToJson();
    var op = await runtime.Commands.SendOrQueueAsync(mac, json);

    Console.WriteLine(op.Status + " " + op.ResponseJson);

    await runtime.Device.DisconnectAsync();
}

---

3. Mimari özet

Host (UI / console)
    └── Tc101Runtime
            ├── Device          (Tc101DeviceClient — MQTT)
            ├── Fleet           (FleetSession — çoklu cihaz operasyonları)
            ├── Commands        (CommandService — SendOrQueue + auto-drain)
            ├── DeviceDirectory (görülen cihazlar + whitelist/blacklist)
            ├── EmqxClients     (REST → docker → export)
            ├── CommandQueue    (SqlCommandQueueStore | Null)
            ├── QueueDispatcher
            └── TrafficLog      (SqlTrafficLogStore | Null)

Katman	Sorumluluk
Mqtt	Ham broker client (IMqttBrokerClient)
Session	Oturum, job korelasyonu, filo, CommandService
Protocol	Zarf, komut tipleri, factory, katalog
Devices	Registry + access gate
Queue	Offline mutation kuyruğu
Emqx	Broker client listesi
Traffic	Opsiyonel MQTT payload log
Configuration	Options + WorkbenchSettings

---

4. Ayarlar

4.1 WorkbenchSettings

Masaüstü host’lar için tek JSON dosyası. Varsayılan yol:

%AppData%\Technolife\Tc101Mqtt\settings.json

var settings = WorkbenchSettings.LoadOrCreate();
settings.Broker.Password = "...";
settings.Save();

Özellikler: Broker, Emqx, Protocol, Queue, DeviceAccess, TrafficLog.

LoadOrCreate yapısal varsayılanları uygular (localhost’ta technolife topic’leri, EMQX açık). Parola / SQL CS enjekte etmez.

4.2 BrokerOptions (MQTT)

Alan	Açıklama	Varsayılan
Host	Broker adresi	localhost
Port	Port	1883
UseTls	TLS	false
AllowUntrustedCertificates	Localhost TLS için otomatik açılabilir	false
ClientId	MQTT client id	tc101-workbench-{Machine}
Username / Password	Broker kimliği	boş / boş
KeepAlive	Keep-alive	60 sn
CommunicationTimeout	Bağlantı timeout	15 sn
CleanSession	Clean session	true
AutoReconnectDelayMs	Yeniden bağlanma gecikmesi	3000

Sabitler: LocalHost, DefaultPlainPort (1883), DefaultTlsPort (8883).

4.3 ProtocolOptions

Alan	Açıklama	Varsayılan
AppKey	TC101 app_key	0x112233445566
StartingJobId	İlk job numarası	1001
DefaultCommandTimeout	Normal komut timeout	15 sn
BulkTransferTimeout	Bulk (upload) timeout	30 sn
UseTechnolifeDeviceTopics	technolife/device/{mac}/down\|up	true
SubscribeTechnolifeDeviceWildcard	technolife/device/# subscribe	true
SubscribeWorkspaceWildcard	Legacy {prefix}/#	false
AlsoPublishToLegacyDown	Ayrıca legacy down’a yayınla	false
LegacyMqttPrefix	Legacy prefix	technoli
LegacyDeviceKey	Legacy device key	tc101
AutoAckCardBlocks	card_data (job<0) otomatik ACK	false
AutoAckLogBlocks	log_data otomatik ACK	false
BulkAckMode	null/boş = sonraki blok; abort / repeat / delete	null
EnableAgentDebugLog	AppData NDJSON debug	false

4.4 EmqxOptions

Alan	Açıklama
Enabled	Filo kaynağı açık mı
ApiBaseUrl	Dashboard API (varsayılan http://localhost:18083)
ApiKey / ApiSecret	System → API Key (Basic auth)
Username / Password	ApiKey boşsa yedek
ClientsExportPath	Dashboard export JSON yedek
UseDockerCliFallback	docker exec … emqx ctl clients list
DockerContainerName	Varsayılan emqx-enterprise
PollIntervalSeconds	Host poll aralığı önerisi

Yükleme sırası (EmqxClientSource.LoadAsync): REST → Docker CLI → export dosyası.

4.5 QueueOptions

Alan	Açıklama	Varsayılan
Enabled	Kuyruk açık	false
ConnectionString	SQL Server CS	""
MaxAttempts	Başarısız deneme üst sınırı	5
StuckSendingSeconds	Stuck Sending reclaim	120
RetryBackoffSeconds	İlk backoff	2
MaxRetryBackoffSeconds	Max backoff	30
QueueableCommandTypes	Kuyruğa alınabilir tipler; null/boş ⇒ built-in	built-in

IsConfigured ⇒ Enabled && ConnectionString dolu.

Aynı CS, cihaz registry/access (ve isteğe bağlı traffic log) için de kullanılır.

4.6 DeviceAccessOptions

Alan	Değer
AccessMode	Yalnızca WhitelistOnly

4.7 TrafficLogOptions

Alan	Açıklama
Enabled	Trafik log açık
ConnectionString	Boşsa Queue CS kullanılır
LogInbound / LogOutbound	Yön seçimi (varsayılan true)

---

5. Tc101Runtime

Composition root. Tüm alt sistemleri oluşturur ve birbirine bağlar.

public Tc101Runtime(
    BrokerOptions broker,
    ProtocolOptions protocol = null,
    QueueOptions queue = null,
    EmqxOptions emqx = null,
    ITc101Log log = null,
    DeviceAccessOptions deviceAccess = null,
    TrafficLogOptions trafficLog = null)

Özellikler

Üye	Tip	Açıklama
Device	Tc101DeviceClient	MQTT session
Fleet	FleetSession	Çoklu cihaz send
Commands	CommandService	SendOrQueue + drain
DeviceDirectory	IDeviceDirectory	Cihaz listesi + access
EmqxClients	IEmqxClientSource	Filo yükleyici
CommandQueue	ICommandQueueStore	SQL veya Null
QueueDispatcher	CommandQueueDispatcher	Claim / drain
TrafficLog	ITrafficLogStore	SQL veya Null
Topics	TopicMap	Device.Topics kısayolu
Log	ITc101Log	Enjekte log

Yaşam döngüsü

await runtime.EnsureReadyAsync(ct);   // şema + whitelist SQL load
await runtime.Device.ConnectAsync(ct);
// … kullanım …
await runtime.Device.DisconnectAsync(ct);
runtime.Dispose();

Runtime kurulurken:

• Device.IsDeviceAllowed = DeviceDirectory.IsAllowed
• MQTT Up → DeviceDirectory.RecordSighting
• Auto-drain: whitelist + live Up → DrainDeviceAsync
• Traffic log açıksa TrafficReceived/Published yazılır

---

6. MQTT oturumu

Tc101DeviceClient

await runtime.Device.ConnectAsync(cancellationToken);
await runtime.Device.DisconnectAsync(cancellationToken);
bool connected = runtime.Device.IsConnected;

• Broker parolası boşsa ConnectAsync hata verir.
• Yeniden bağlanma: session açık kaldığı sürece otomatik dener.
• İsteğe bağlı kendi IMqttBrokerClient enjekte edilebilir (test/mock).

Doğrudan gönderim (kuyruk politikası olmadan)

var reply = await runtime.Device.SendToAsync(
    "0c:dc:7e:36:c0:9f",
    runtime.Device.Commands.GetStatus(),
    TimeSpan.FromSeconds(10));

if (reply.IsSuccess) { /* … */ }

Timeout’ta CommandTimeoutException fırlatılır.

Ham publish

await runtime.Device.PublishRawAsync(topic, payloadJson, ct);

Canlılık (MqttFleetActivity)

Son 2 dakika içinde MQTT Up gören cihazlar “live”:

bool live = runtime.Device.FleetActivity.IsRecentlyActive(mac);
var liveIds = runtime.Device.FleetActivity.GetRecentlyActiveClientIds();

Kuyruk drain / SendOrQueue “anında gönder” kararı buna dayanır (EMQX connected yetmez).

---

7. Topic’ler

Technolife (varsayılan firmware)

Yön	Topic
Down (komut)	technolife/device/{mac}/down
Up (cevap/olay)	technolife/device/{mac}/up
Subscribe	technolife/device/#

MAC biçimi: aa:bb:cc:dd:ee:ff (FleetEntry.FormatTechnolifeDeviceId).

TopicMap.TechnolifeDeviceDownTopic(mac);
TopicMap.TechnolifeDeviceUpTopic(mac);
TopicMap.TryParseTechnolifeDeviceTopic(topic, out var key, out var segment);

Legacy prefix ağacı (opsiyonel)

{LegacyMqttPrefix}/{LegacyDeviceKey}/cmd|event|… — SubscribeWorkspaceWildcard / AlsoPublishToLegacyDown ile.

TopicMap.IsDownSegment / IsUpSegment hem technolife hem legacy soneklerini tanır.

---

8. Protokol zarfı ve komutlar

Zarf (Tc101Envelope)

var env = Tc101Envelope.Parse(json);
string type = env.Type;
int job = env.Job;
bool ok = env.IsSuccess;           // error_message none/empty
bool unsolicited = env.IsUnsolicited; // job < 0
string outJson = env.ToJson();

Tipler (Tc101CommandType)

Sabitler: get_status, set_status, get_io, set_io, serial_data, get_config, set_config, get_admin_config, set_admin_config, get_key, set_key, get_card, set_card, delete_card, upload_card_data, card_data, access_data, get_zone, set_zone, delete_zone, get_action, set_action, delete_action, upload_log_data, log_data, delete_log, get_date, set_date, screen komutları, read_card, …

Factory (runtime.Device.Commands)

Hazır üreticiler (örnekler):

var c = runtime.Device.Commands;

c.GetStatus();
c.GetIoAll();
c.SetIo(value: 1, holdTimeSeconds: 10, 5, 6);
c.SerialText(port: 2, text: "ping", waitTimeMs: 2000);
c.GetConfig();                 // tüm config
c.GetConfig("application");
c.SetConfig(jObject);
c.GetAdminConfig();
c.SetAdminConfig(jObject);
c.GetKey();
c.SetKey("0x112233445566");
c.GetCard("0x02DC3C57C9");
c.SetCard(ids, begin, end, zoneId, groupId, escortLevel, password, config, iface);
c.DeleteCard("0x02DC3C57C9");
c.UploadCardData();
c.AckCardBlock();              // veya "abort" / "repeat"
c.GetZoneAll();
c.SetFullDayZone(1);           // 00:00–23:59
c.SetZone(zoneListJArray);
c.DeleteZone(11, 12);
c.GetActionAll();
c.SetAction(actionListJArray);
c.DeleteAction(5, 6);
c.UploadLogData();
c.AckLogBlock();               // veya abort/repeat/delete
c.DeleteLogAll();
c.Reboot();
c.FirmwareUpdate();
c.LoadDefaults();
c.GetDate();
c.SetDate("2026-09-08 12:00:00");
c.GetScreenPagesAll();
c.SetScreenPages(pageList);
c.ShowScreenMessage(pageId, holdTime, priority, text);
c.ReadCard(cardId, expDate, expTime);

// Herhangi bir tip:
c.Create("ping", data: null);

Gönderimde job numarası SendToAsync / Fleet tarafından atanır; factory’deki örnek job üzerine yazılır.

Katalog (Tc101CommandCatalog)

UI için Türkçe grup/ad/açıklama + örnek JSON:

foreach (var item in Tc101CommandCatalog.Items)
{
    // item.Group, item.Name, item.Type, item.Description, item.SampleJson, item.ShowInCatalog
}

Katalogda olmayan komutlar için Create veya kendi JSON’unuz kullanılabilir.

Hata (Tc101Error)

Tc101Error.IsSuccess("none");  // true
Tc101Error.IsSuccess("timeout"); // false

---

9. Komut gönderme ve kuyruk

Önerilen yol: CommandService

// Tek cihaz
var op = await runtime.Commands.SendOrQueueAsync(mac, json, timeout);

// Çoklu
var ops = await runtime.Commands.SendOrQueueManyAsync(macs, json, timeout);

Politika (requireLiveUpForImmediate = true, varsayılan):

1. Tip queueable ve kuyruk açık ve son 2 dk MQTT Up yok → SQL Pending
2. Aksi halde MQTT ile gönder
3. Timeout / Error + queueable → kuyruğa al

CardBulkLoad gibi senaryolarda önce MQTT denemek için:

await runtime.Commands.SendOrQueueAsync(mac, json, timeout, ct, requireLiveUpForImmediate: false);

CommandOperation durumları

Queued, Sent, Ok, Error, Timeout

Queueable tipler (varsayılan)

set_card, delete_card, set_zone, delete_zone, set_action, delete_action, set_config, set_admin_config, set_key, set_date, set_screen_page, set_screen_text, screen_data, set_status

Özelleştirme:

settings.Queue.QueueableCommandTypes = new[] { "set_card", "set_zone", "custom_write" };

QueuedCommandTypes.IsQueueable("set_card", settings.Queue);
QueuedCommandTypes.ResolveTypes(settings.Queue);

get_*, upload_*, card_data, log_data varsayılan olarak kuyruğa alınmaz.

Dispatcher

await runtime.QueueDispatcher.EnqueueAsync(mac, type, json);
await runtime.QueueDispatcher.DrainDeviceAsync(mac);
await runtime.QueueDispatcher.DrainManyAsync(macs);
await runtime.Commands.DrainLiveAllowedAsync(); // live Up + whitelist

Runtime, Up + whitelist cihazlarda otomatik drain bağlar.

Store API

await runtime.CommandQueue.EnsureSchemaAsync();
var pending = await runtime.CommandQueue.CountPendingAsync();
var rows = await runtime.CommandQueue.ListActiveAsync(300);
await runtime.CommandQueue.CancelAsync(id);

Durumlar: Pending, Sending, Sent, Failed, Cancelled.

Backoff: başarısız drain sonrası 2s → … → max 30s. Stuck Sending → reclaim → Pending.

Fleet (doğrudan, kuyruksuz politika)

var op = await runtime.Fleet.SendToAsync(mac, json, timeout);
var ops = await runtime.Fleet.SendToManyAsync(macs, json, timeout);

---

10. Cihaz dizini ve erişim (whitelist)

Politika: WhitelistOnly

1. Blacklist → işleme
2. Whitelist’te yok (boş liste dahil) → işleme
3. Aksi → işle (job korelasyonu, AutoAck, MessageReceived)

Cihaz yine de listede görünür (EMQX veya MQTT Up sighting). Broker ACL değişmez; filtre uygulama katmanındadır.

API

await runtime.DeviceDirectory.EnsureReadyAsync();
var list = await runtime.DeviceDirectory.GetDevicesAsync();
var refreshed = await runtime.DeviceDirectory.RefreshFromEmqxAsync();

await runtime.DeviceDirectory.SetWhitelistAsync(mac);
await runtime.DeviceDirectory.SetBlacklistAsync(mac);
await runtime.DeviceDirectory.RemoveFromListsAsync(mac);

bool ok = runtime.DeviceDirectory.IsAllowed(mac);

DeviceRecord alanları: DeviceKey, FirstSeenUtc, LastSeenUtc, LastUpUtc, EmqxConnected, HasLiveMqttUp, Source, IsWhitelisted, IsBlacklisted, IsAllowed.

Olaylar: DevicesChanged, AccessChanged.

SQL yoksa access bellek içidir (process restart’ta kaybolur). Queue CS varsa Tc101DeviceAccess / Tc101DeviceRegistry kalıcıdır.

---

11. EMQX filo kaynağı

var loaded = await runtime.EmqxClients.LoadAsync(ct);
// loaded.Clients, loaded.Source ("API"|"docker"|"export"), loaded.Error

var fleet = FleetEntry.FromEmqxClients(loaded.Clients);
foreach (var e in fleet)
{
    var id = e.ResolveClientId();
    bool online = e.IsConnected;
}

FleetEntry.IsExcludedClient tc101-workbench* ve emqx_* istemcilerini düşürür.

Directory refresh, EMQX listesini MQTT Up overlay ile birleştirir.

---

12. Trafik log

Açıkken inbound/outbound MQTT payload’ları Tc101MqttTraffic tablosuna yazılır.

settings.TrafficLog.Enabled = true;
// CS boşsa Queue.ConnectionString kullanılır

var rows = await runtime.TrafficLog.QueryAsync(take: 200, deviceKey: mac);
// Direction In/Out, Topic, Payload, Processed (gate sonucu), Utc

Processed == false: cihaz görüldü ama whitelist değil / blacklist.

---

13. Olaylar (events)

Host UI bağlama örnekleri:

runtime.Device.ConnectionChanged += (s, e) => { /* e.Connected, e.Reason */ };
runtime.Device.MessageReceived += (s, e) => { /* e.Envelope, e.DeviceKey, e.Correlated */ };
runtime.Device.MessageIgnored += (s, e) => { /* gate reddi */ };
runtime.Device.TrafficReceived += (s, e) => { /* Up trafik */ };
runtime.Device.TrafficPublished += (s, e) => { /* Down publish */ };
runtime.Device.DeviceSighted += (s, e) => { /* e.DeviceKey, e.IsUp */ };
runtime.Device.RawPayloadReceived += (s, payload) => { };

runtime.Fleet.OperationChanged += (s, e) => { /* e.Operation */ };
runtime.QueueDispatcher.QueueChanged += (s, e) => { /* e.Command */ };
runtime.DeviceDirectory.DevicesChanged += (s, e) => { RefreshDeviceList(); };

MqttTrafficEventArgs: Direction (Up/Down), Topic, Payload, DeviceKey, Parsed, Envelope, Type.

---

14. SQL şema

Queue CS ile EnsureReadyAsync / store EnsureSchemaAsync şunları oluşturur:

Tablo	Amaç
Tc101CommandQueue	Offline komut kuyruğu
Tc101DeviceRegistry	Görülen cihazlar
Tc101DeviceAccess	Whitelist / Blacklist satırları
Tc101MqttTraffic	Opsiyonel trafik log (TrafficLog.Enabled)

Örnek CS:

Server=127.0.0.1,12121;Database=Tc101Mqtt;User Id=sa;Password=…;TrustServerCertificate=True

---

15. Gözlemlenebilirlik

ITc101Log

public interface ITc101Log
{
    void Info(string message, object data = null);
    void Warn(string message, object data = null);
    void Error(string message, object data = null);
}

Runtime’a enjekte edin. Varsayılan: NullTc101Log. Debug adaptörü: AgentDebugTc101Log.

AgentDebugLog

Protocol.EnableAgentDebugLog = true iken %AppData%\Technolife\Tc101Mqtt\ altına NDJSON yazar. Üretimde kapalı tutun.

---

16. Host checklist

Minimal host:

1. BrokerOptions (+ parola) ve isteğe bağlı Queue/Emqx/TrafficLog ayarla
2. new Tc101Runtime(...)
3. EnsureReadyAsync
4. Event’leri UI’ya bağla
5. Device.ConnectAsync
6. DeviceDirectory.RefreshFromEmqxAsync
7. İşlenecek MAC’leri SetWhitelistAsync
8. Komutları Commands.SendOrQueueAsync / SendOrQueueManyAsync ile gönder
9. Kuyruk UI: CommandQueue.ListActiveAsync, CancelAsync, manuel DrainLiveAllowedAsync
10. Disconnect + Dispose

Tehlikeli komut onayı (set_admin_config, set_key, reboot, …) host UI sorumluluğundadır; kütüphane engellemez.

---

17. Sınırlar

• Queue dedupe/coalesce yok; aynı komut birden fazla Pending olabilir.
• Whitelist boşken hiçbir inbound işlenmez (cihaz listede kalır).
• EMQX ACL değiştirilmez; cihazlar broker’a bağlanmaya devam eder.
• Serial multi-frame aynı job collector, zengin sectioned config/action builder’lar ve typed access_data parse henüz first-class helper değildir; ham JSON / Create ile yapılabilir.
• Bu paket bir NuGet feed’ine yayınlanmamış olabilir; solution içi ProjectReference kullanın.

---

Örnek: offline kart yazma

settings.Queue.Enabled = true;
settings.Queue.ConnectionString = cs;

using (var rt = new Tc101Runtime(settings.Broker, settings.Protocol, settings.Queue, settings.Emqx))
{
    await rt.EnsureReadyAsync();
    await rt.Device.ConnectAsync();
    await rt.DeviceDirectory.SetWhitelistAsync(mac);

    var env = rt.Device.Commands.SetCard(
        new[] { "0x02DC3C57C9" },
        begin: "2025-01-01",
        end: "2025-12-31",
        zoneId: 1,
        groupId: 0,
        escortLevel: 0,
        password: 0,
        config: 0,
        iface: 99);

    // Up yoksa Pending; Up gelince Runtime auto-drain eder
    var op = await rt.Commands.SendOrQueueAsync(mac, env.ToJson());
}

---

Testler

dotnet test src/Technolife.Tc101.Communication.Tests/Technolife.Tc101.Communication.Tests.csproj

Smoke (broker varsa canlı MQTT):

dotnet run --project src/Technolife.Tc101.SmokeTest/Technolife.Tc101.SmokeTest.csproj

---

İlgili host projeler

Proje	Rol
Technolife.Tc101.Workbench.Net8 / .Net48	WinForms filo konsolu
Technolife.Tc101.CardBulkLoad	Toplu zone + kart yükleme
Technolife.Tc101.SmokeTest	Konu/kuyruk/katalog + canlı MQTT smoke
Technolife.Tc101.Communication.Tests	xUnit birim testleri