# Twinzo C# development kit .NET 5 SDK for digital twin developers used to connect your C# code with twinzo platform. Providing whole API Endpoint communication methods and data contracts for easy serialization and transporting. ## Nuget package SDK Nuget package is publicly available for developers to use twinzo platform API right from Visual Studio IDE. Please read [Package & Repository - tDevKit](https://gitlab.twinzo.eu/digital-twin/twinzo/tdevkit/-/packages) section for more informations and instructions do get known, how to install SDK. ## API Rest json/protobuf API for registered twinzo clients and partners provides fully capable interface for bidirectional digital twin integration. [API Endpoint](https://twin.rtls.solutions/api/swagger/ui/index#/) for each digital twin module uses same authorization methods to provide all system unification into single instance - twinzo. ## Documentation & Examples (V3) ### Initialization The first thing you need to do is create the base object by which the functionality will be accessible: ```c# ConnectionOptionsBuilder ConnectionOptionsBuilder = new ConnectionOptionsBuilder(); ConnectionOptions connectionOptions = optionsBuilder .Url("https://twin.rtls.solutions/api") .Client("YourClient") .BranchGuid("YourBranchGuid") .Timeout(1000) .ApiKey("YourApiKey") .Version(ConnectionOptions.VERSION_3) .Build(); DevkitConnectorV3 devkitConnector = (DevkitConnectorV3) DevkitFactory.CreateDevkitConnector(connectionOptions); ``` Through the `DevkitConnectorV3` object are accessible all the functions implemented in tDevkit. As of **V3**, Most of the functionality is ready to be used after specifying the Api Key in `ConnectionOptions` object. However, there is a small number of functions you need to be authenticated for due to their nature. These functions are mentioned in the [Full list of functions](#full-list-of-functions-v3). ### Examples Below are a few examples with dummy data. #### Getting objects Getting all objects (f.e. Area type): ```c# AreaContract[] areas = await devkitConnector.GetAreas(); ``` Getting an object by ID: ```c# DeviceContract device = await devkitConnector.GetDevice(3); ``` Getting an object by login (if said object's class has `login` property): ```c# SensorContract sensor = await devkitConnector.GetSensor("login"); ``` \ Most of the `GET` functions are able to be further customized to your needs by taking in `queryString` parameter. With this parameter you can specify additional query options (order, limit, expand etc.) according to the [OData standard](https://www.odata.org/documentation/odata-version-3-0/url-conventions/).\ Ordering by property: ```c# LayerContract[] layers = await devkitConnector.GetLayers("?$orderby=Updated"); ``` Expanding by another related data model: ```c# SectorContract sector = await devkitConnector.GetSector(1, "?$expand=Beacons"); ``` #### Adding objects Successfully adding an object returns it back with its alocated ID (and with freshly generated GUID, if such object is in question). ```c# DeviceContract deviceDummy = new DeviceContract { Mac = "00:00:00:00:00:00", BranchId = 1, SectorId = 1, Login = "login", Title = "login", X = 100.0, Y = 100.0, IsMoving = false, FallStatus = FallType.OK, DeviceTypeId = 8, Position = false, Geofence = false }; DeviceContract device = await devkitConnector.AddDevice(deviceDummy); ``` ```c# SensorDataContract data1 = new SensorDataContract { Quantity = "Temperature", Value = "16", Unit = "°C", DataType = "Single" }; SensorDataContract data2 = new SensorDataContract { Quantity = "Humidity", Value = "31", Unit = "%", DataType = "Single" }; SensorDataContract[] sensorDataContracts = new SensorDataContract[] { data1, data2 }; SensorContract sensorDummy = new SensorContract { Login = "login", Title = "title", SectorId = 2, SensorData = sensorDataContracts, }; SensorContract sensor = await devkitConnector.AddSensor(sensorDummy); ``` #### Localization ```c# DistanceContract[] distanceContract1 = new DistanceContract[] { new DistanceContract {BeaconId = 34, RSSI= -55}, new DistanceContract {BeaconId = 35, RSSI= -60}, new DistanceContract {BeaconId = 36, RSSI= -45} }; LocationContract[] locationContract = new LocationContract[] { new LocationContract {SectorId = 1, Battery = 100, IsMoving = true, Timestamp = 1599644652178, X = 0, Y = 0, Z = 0, Interval = 300, Distances = distanceContract1 }, new LocationContract {SectorId = 2, Battery = 100, IsMoving = true, Timestamp = 1599644652178, X = 0, Y = 0, Z = 0, Interval = 300, Distances = distanceContract1 }, new LocationContract {SectorId = 3, Battery = 100, IsMoving = true, Timestamp = 1599644652178, X = 0, Y = 0, Z = 0, Interval = 300, Distances = distanceContract1 }, new LocationContract {SectorId = 4, Battery = 100, IsMoving = true, Timestamp = 1599644652178, X = 0, Y = 0, Z = 0, Interval = 300, Distances = distanceContract1 }, }; DeviceLocationContract[] deviceLocationContract = new DeviceLocationContract[] { new DeviceLocationContract { Login = "login", Locations = locationContract } }; await devkitConnector.AddLocalizationData(deviceLocationContract); ``` #### Sensor Data ```c# SensorDataContract data1 = new SensorDataContract { Quantity = "Temperature", Value = "16", Unit = "°C", DataType = "Single" }; SensorDataContract data2 = new SensorDataContract { Quantity = "Humidity", Value = "31", Unit = "%", DataType = "Single" }; SensorDataContract data3 = new SensorDataContract { Quantity = "CO2", Timestamp = 1614599484673, Value = "800", DataType = "Int32", Unit = "unit" }; SensorDataContract[] sensorDataContracts = new SensorDataContract[] { data1, data2, data3 }; SensorContract sensor = new SensorContract { Login = "login", SensorData = sensorDataContracts, }; SensorContract[] sensorContracts = new SensorContract[] { sensor }; await devkitConnector.AddSensorData(sensorContracts); ``` ### Full list of functions * **Areas** * GetAreas() - Get all areas * GetArea(id) - Get area by ID * **Authorization** * Authenticate(login, password) - Authenticate with login and password as user/device/sensor * Beacons * GetBeacons() - Get all beacons * GetBeacon(id) - Get beacon by ID * AddBeacon(beaconContract) - Add a beacon with specified properties * UpdateBeacon(beaconContract) - Update an existing beacon with new properties * DeleteBeacon(id) - Delete an existing beacon by ID * Branches * GetBranches() - Get all branches * GetBranch(id) - Get branch by ID * Clients * GetClients() - Get all clients * Configuration * GetBranchConfiguration(key) - Get branch configuration with specified key * GetAccountConfiguration(key) - Get account configuration with specified key * GetConfigurationLastChange(key) - Get branch configuration with specified key * Devices * GetDevices() - Get all devices * GetDevice(id) - Get device by ID * GetDevice(login) - Get device by login * GetDynamicDevices() - Get devices with dynamic position * GetDynamicDevicesShort() - Get shortened form of dynamic devices grouped by sectors * AddDevice(deviceContract) - Add a device with specified properties * UpdateDevice(deviceContract) - Update an existing device with new properties * DeleteDevice(id) - Delete an existing device by ID * Layers * GetLayers() - Get all layers * GetLayer(id) - Get layer by ID * Localization * AddLocalizationData(deviceLocationContract) - Add localization data for multiple devices in batch mode * AddLocalizationData(locationContract) - Add localization data for single device (in order to do this you need to be **authenticated** as said device) * Sectors * GetSectors() - Get all sectors * GetSector(id) - Get sector by ID * AddSector(sectorContract) - Add a sector with specified properties * UpdateSector(sectorContract) - Update an existing sector with new properties * DeleteSector(id) - Delete an existing sector by ID * Sensors * GetSensors() - Get all sensors * GetSensor(id) - Get sensor by ID * GetSensor(login) - Get sensor by login * AddSensor(sensorContract) - Add a sensor with specified properties * UpdateSensor(sensorContract) - Update an existing sensor with new properties * DeleteSensor(id) - Delete an existing sensor by ID * AddSensorData(sensors) - Add sensor data for multiple sensors in batch mode * AddSensorData(sensorData) - Add sensor data for single sensor (in order to do this you need to be **authenticated** as said sensor) * GetSensorAppInfo() - Get information (version, size) about the sensor app * Shifts * GetShifts() - Get all shifts * GetShift(id) - Get shift by ID * Users * GetUserInfo() - Get information about the current user (in order to do this you need to be **authenticated** as said user) * Utils * GetDemoFilesInfo() - Get information (version, size, name) about all the demo files * GetFile(fileName) - Get byte representation of the specified file * GetDemoFile(fileName) - Get byte representation of the specified demo file * GetUnityLastVersion(platform) - Get the last version of the Unity app * GetUnityBundleInfo(bundleName) - Get information (version, size, name) about the Unity Bundle ## Future features - **protobuffers** serialization - automated order system(AOS) for logistics integration - TCS implementation - Logs implementation - **MQTT** communication protocol implementation