Skip to content
Snippets Groups Projects
README.md 7.38 KiB
Newer Older
Patrik Paško's avatar
Patrik Paško committed
# Twinzo C# development kit
Patrik Paško's avatar
Patrik Paško committed
.NET 5 SDK for digital twin developers used to connect your C# code with twinzo platform.

Patrik Paško's avatar
Patrik Paško committed
Providing whole API Endpoint communication methods and data contracts for easy serialization and transporting.
Patrik Paško's avatar
Patrik Paško committed

Patrik Paško's avatar
Patrik Paško committed
## Nuget package
SDK Nuget package is publicly available for developers to use twinzo platform API right from Visual Studio IDE. 
Patrik Paško's avatar
Patrik Paško committed

Michal Ondrejička's avatar
Michal Ondrejička committed
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. 
Patrik Paško's avatar
Patrik Paško committed

Patrik Paško's avatar
Patrik Paško committed
## 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.

Michal Ondrejička's avatar
Michal Ondrejička committed
## Documentation & Examples (V3)

Michal Ondrejička's avatar
Michal Ondrejička committed
### Initialization
Michal Ondrejička's avatar
Michal Ondrejička committed
The first thing you need to do is create the base object by which the functionality will be accessible:
Michal Ondrejička's avatar
Michal Ondrejička committed
```c# 
Michal Ondrejička's avatar
Michal Ondrejička committed
ConnectionOptionsBuilder ConnectionOptionsBuilder = new ConnectionOptionsBuilder();
Michal Ondrejička's avatar
Michal Ondrejička committed
ConnectionOptions connectionOptions = optionsBuilder
	.Url("https://twin.rtls.solutions/api")
	.Client("YourClient")
	.BranchGuid("YourBranchGuid")
	.Timeout(1000)
	.ApiKey("YourApiKey")
	.Version(ConnectionOptions.VERSION_3)
	.Build();
Michal Ondrejička's avatar
Michal Ondrejička committed
	
DevkitConnectorV3 devkitConnector = (DevkitConnectorV3) DevkitFactory.CreateDevkitConnector(connectionOptions);
```
Michal Ondrejička's avatar
Michal Ondrejička committed
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");
```
\
Michal Ondrejička's avatar
Michal Ondrejička committed
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/).\
Michal Ondrejička's avatar
Michal Ondrejička committed
Ordering by property:
```c#
LayerContract[] layers = await devkitConnector.GetLayers("?$orderby=Updated");
```
Expanding by another related data:
```c#
SectorContract sector = await devkitConnector.GetSector(1, "?$expand=Beacons");
```
#### Adding objects
Successfully adding an object returns it 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 };
Michal Ondrejička's avatar
Michal Ondrejička committed
SensorContract sensor = new SensorContract
{
    Login = "login",
    SensorData = sensorDataContracts,
};
SensorContract[] sensorContracts = new SensorContract[] { sensor };

await devkitConnector.AddSensorData(sensorContracts);
```
### Full list of functions
* Areas
	* GetAreas()
	* GetArea(id)
* Authorization
	* Authenticate(login, password)
* Beacons
	* GetBeacons()
	* GetBeacon(id)
	* AddBeacon(beaconContract)
	* UpdateBeacon(beaconContract)
	* DeleteBeacon(id)
* Branches
	* GetBranches()
	* GetBranch(id)
* Clients
	* GetClients()
* Configuration
	* GetBranchConfiguration(key)
	* GetAccountConfiguration(key)
	* GetConfigurationLastChange(key)
* Devices
	* GetDevices()
	* GetDevice(id)
	* GetDevice(login)
	* GetDynamicDevices()
	* GetDynamicDevicesShort()
	* AddDevice(deviceContract)
	* UpdateDevice(deviceContract)
	* DeleteDevice(id)
* Layers
	* GetLayers()
	* GetLayer(id)
* Localization
	* AddLocalizationData(deviceLocationContract)
	* AddLocalizationData(locationContract)
* Sectors
	* GetSectors()
	* GetSector(id)
	* AddSector(sectorContract)
	* UpdateSector(sectorContract)
	* DeleteSector(id)
* Sensors
	* GetSensors()
	* GetSensor(id)
	* GetSensor(login)
	* AddSensor(sensorContract)
	* UpdateSensor(sensorContract)
	* DeleteSensor(id)
	* AddSensorData(sensors)
	* AddSensorData(sensorData)
	* GetSensorAppInfo()
* Shifts
	* GetShifts()
	* GetShift(id)
* Users
	* GetUserInfo()
* Utils
	* GetDemoFilesInfo()
	* GetFile(fileName)
	* GetDemoFile(fileName)
	* GetUnityLastVersion(platform)
	* GetUnityBundleInfo(bundleName)
Patrik Paško's avatar
Patrik Paško committed
## Future features
- **protobuffers** serialization
- automated order system(AOS) for logistics integration
Patrik Paško's avatar
Patrik Paško committed
- **MQTT** communication protocol implementation