diff --git a/README.md b/README.md index 76b5242127a61e76e5eb0eb78d3c33cd00d28aa9..46959d59973b5280615f1264bb9ad0cfa3d20bdc 100644 --- a/README.md +++ b/README.md @@ -15,27 +15,224 @@ Rest json/protobuf API for registered twinzo clients and partners provides fully ## 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(); +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: +```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 }; -Through the `DevkitConnectorV3` object are accessible all the functions implemented in tDevkit. +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) -### List of functions -TBA ## Future features - **protobuffers** serialization