Speciális eszközmodell létrehozásaCreate an advanced device model

Ez a útmutató az egyéni eszköz modelljét definiáló JSON-és JavaScript-fájlokat ismerteti.This how-to guide describes the JSON and JavaScript files that define a custom device model. A cikk néhány minta típusú eszköz-definíciós fájlt tartalmaz, és bemutatja, hogyan töltheti fel őket az eszköz szimulációs példányára.The article includes some sample device model definition files and shows you how to upload them to your Device Simulation instance. Speciális eszköz-modelleket hozhat létre, amelyek reális eszköz-viselkedést szimulálnak a teszteléshez.You can create advanced device models to simulate more realistic device behaviors for your testing.

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.If you don't have an Azure subscription, create a free account before you begin.

ElőfeltételekPrerequisites

A jelen útmutató lépéseit követve az Azure-előfizetésében az eszköz-szimuláció üzembe helyezett példánya szükséges.To follow the steps in this how-to guide, you need a deployed instance of Device Simulation in your Azure subscription.

Ha még nem telepítette az eszköz-szimulációt, tekintse meg a következőt: eszköz-szimulációs telepítés a githubon.If you haven't deployed Device Simulation yet, see Device Simulation deployment on GitHub.

Eszközszimuláció megnyitásaOpen Device Simulation

Ha még nem telepítette az eszköz-szimulációt, tekintse meg a következőt: eszköz-szimulációs telepítés a githubon.If you haven't deployed Device Simulation yet, see Device Simulation deployment on GitHub.

EszközmodellekDevice models

Minden szimulált eszköz egy adott eszköz modelljéhez tartozik, amely meghatározza a szimulációs viselkedést.Each simulated device belongs to a specific device model that defines the simulation behavior. Ez a viselkedés magában foglalja a telemetria küldésének gyakoriságát, a küldendő üzenetek típusát és a támogatott metódusokat.This behavior includes how frequently to send telemetry, what kind of messages to send, and the supported methods.

Az eszköz modelljét JSON-eszköz definíciós fájlja és JavaScript-fájlok készlete alapján határozhatja meg.You define a device model using a JSON device definition file and a set of JavaScript files. Ezek a JavaScript-fájlok határozzák meg a szimulációs viselkedést, például a véletlenszerű telemetria és a metódus logikáját.These JavaScript files define the simulation behavior such as the random telemetry and the method logic.

Egy tipikus eszköz modellje:A typical device model has:

  • Egy JSON-fájl minden eszköz-modellhez (például elevator.json).One JSON file for each device model (for example, elevator.json).
  • Egy JavaScript-viselkedési parancsfájl minden eszköz-modellhez (például elevator-state.js)One JavaScript behavior script file for each device model (for example, elevator-state.js)
  • Egy JavaScript-metódus parancsfájlja minden eszköz-metódushoz (például elevator-go-down.js)One JavaScript method script file for each device method (for example, elevator-go-down.js)

Megjegyzés

Nem minden eszköz modell definiál metódusokat.Not all device models define methods. Ezért előfordulhat, hogy az eszköz modellje nem rendelkezik metódus-parancsfájlokkal.Therefore a device model may or may not have method scripts. Azonban minden eszköz modellnek rendelkeznie kell egy viselkedési parancsfájllal.However, all device models must have a behavior script.

Eszköz definíciós fájljaDevice definition file

Minden eszköz definíciós fájlja egy szimulált eszköz modelljének részleteit tartalmazza, beleértve a következő információkat:Each device definition file contains details of a simulated device model, including the following information:

  • Eszköz modell neve: karakterlánc.Device model name: string.
  • Protokoll: AMQP | MQTT | HTTP.Protocol: AMQP | MQTT | HTTP.
  • A kezdeti eszköz állapota.The initial device state.
  • Milyen gyakran frissíti az eszköz állapotát.How often to refresh the device state.
  • Az eszköz állapotának frissítéséhez használandó JavaScript-fájl.Which JavaScript file to use to refresh the device state.
  • A küldendő telemetria-üzenetek listája, amelyek mindegyike egy adott gyakorisággal rendelkezik.A list of telemetry messages to send, each with a specific frequency.
  • A telemetria-üzenetek sémája, amelyet a háttérbeli alkalmazás használ a kapott telemetria elemzéséhez.The schema of the telemetry messages, used by back-end application to parse the telemetry received.
  • A támogatott metódusok és az egyes módszerek szimulálásához használandó JavaScript-fájl listája.A list of supported methods and the JavaScript file to use to simulate each method.

Fájl sémájaFile schema

A séma verziószáma mindig "1.0.0", és a fájl formátumára vonatkozik:The schema version is always "1.0.0" and is specific to the format of this file:

"SchemaVersion": "1.0.0"

Eszköz modell leírásaDevice model description

A következő tulajdonságok leírják az eszköz modelljét.The following properties describe the device model. Mindegyik típus egyedi azonosítóval, szemantikai verzióval, névvel és leírással rendelkezik:Each type has a unique identifier, a semantic version, a name, and a description:

"Id": "chiller-01",
"Version": "0.0.1",
"Name": "Chiller",
"Description": "Chiller with external temperature and humidity sensors."

IoT protokollIoT Protocol

A IoT-eszközök különböző protokollokkal csatlakozhatnak.IoT devices can connect using different protocols. A szimuláció a AMQP, a MQTT vagy a http használatát teszi lehetővé:The simulation lets you use either AMQP, MQTT, or HTTP:

"Protocol": "AMQP"

Szimulált eszköz állapotaSimulated device state

Minden szimulált eszköz belső állapotú, amelyet meg kell határozni.Each simulated device has an internal state, which must be defined. Az állapot meghatározza azokat a tulajdonságokat is, amelyek a telemetria jelentésekben szerepelhetnek.The state also defines the properties that can be reported in telemetry. Előfordulhat például, hogy egy hűtőnek van egy kezdeti állapota, például:For example, a chiller might have an initial state such as:

"InitialState": {
    "temperature": 50,
    "humidity": 40
},

Több érzékelővel rendelkező mozgó eszköz több tulajdonsággal rendelkezhet, például:A moving device with several sensors might have more properties, for example:

"InitialState": {
    "latitude": 47.445301,
    "longitude": -122.296307,
    "speed": 30.0,
    "speed_unit": "mph",
    "cargotemperature": 38.0,
    "cargotemperature_unit": "F"
}

A szimulációs szolgáltatás a memóriában tárolja az eszköz állapotát, és bemenetként adja meg a JavaScript-függvényt.Device state is kept in memory by the simulation service, and provided as input to the JavaScript function. A JavaScript-függvény dönthet úgy, hogy:The JavaScript function could decide:

  • Az állapot figyelmen kívül hagyásához és véletlenszerű adatmennyiség létrehozásához.To ignore the state and generate some random data.
  • Az eszköz állapotának frissítése valamilyen reális módon egy adott forgatókönyv esetén.To update the device state in some realistic way for a given scenario.

Az állapotot létrehozó függvény bemenetként is kap:The function that generates the state also receives as input:

  • Az eszköz azonosítója.The device ID.
  • Az eszköz modellje.The device model.
  • Az aktuális idő.The current time. Ez az érték lehetővé teszi, hogy az eszköz és az idő alapján különböző adategységeket lehessen készíteni.This value makes it possible to generate different data by device and by time.

Telemetria-üzenetek generálásaGenerating telemetry messages

A szimulációs szolgáltatás több telemetria-típust is küldhet az egyes eszközökhöz.The simulation service can send several telemetry types for each device. A telemetria jellemzően az eszköz állapotáról származó adatokra vonatkozik.Typically, telemetry includes data from the device state. Előfordulhat például, hogy egy szimulált helyiség 10 másodpercenként adatokat küld a hőmérsékletről és a nedvességről.For example, a simulated room might send information about temperature and humidity every 10 seconds. Jegyezze fel a következő kódrészletben található helyőrzőket, amelyek automatikusan az eszköz állapotában szereplő értékekkel lesznek lecserélve:Note the placeholders in the following snippet, which are automatically replaced with values from the device state:

"Telemetry": [
    {
        "Interval": "00:00:10",
        "MessageTemplate":
            "{\"temperature\":${temperature},\"temperature_unit\":\"${temperature_unit}\",\"humidity\":\"${humidity}\"}",
        "MessageSchema": {
            "Name": "RoomComfort;v1",
            "Format": "JSON",
            "Fields": {
                "temperature": "double",
                "temperature_unit": "text",
                "humidity": "integer"
            }
        }
    }
],

A helyőrzők a $ {Name} speciális szintaxist használják, ahol a név a JavaScript Main függvény által visszaadott Eszközállapot-objektum kulcsa.The placeholders use a special syntax ${NAME} where NAME is a key from the device state object returned by the JavaScript main function. A sztringeket idézőjelek közé kell állítani, míg a számok nem.Strings should be quoted, while numbers shouldn't.

Üzenet sémájaMessage schema

Minden üzenet típusának jól definiált sémával kell rendelkeznie.Each message type must have a well-defined schema. Az üzenet sémája IoT Hub is közzé van téve, így a háttérbeli alkalmazások újra felhasználhatják az adatokat a bejövő telemetria értelmezéséhez.The message schema is also published to IoT Hub, so that back-end applications can reuse the information to interpret the incoming telemetry.

A séma támogatja a JSON formátumot, amely lehetővé teszi az egyszerű elemzést, átalakítást és elemzést több rendszer és szolgáltatás között.The schema supports JSON format, which allows for easy parsing, transformation and analytics, across several systems and services.

A sémában felsorolt mezők a következő típusokból állhatnak:The fields listed in the schema can be of the following types:

  • Objektum – szerializált JSON használatávalObject - serialized using JSON
  • Bináris – Base64 használatával szerializáltBinary - serialized using base64
  • SzövegText
  • Logikai értékBoolean
  • Egész számInteger
  • DuplaDouble
  • DateTimeDateTime

Támogatott módszerekSupported methods

A szimulált eszközök reagálnak a metódus hívására is, ebben az esetben bizonyos logikát hajtanak végre, és választ nyújtanak.Simulated devices can also react to method calls, in which case they execute some logic and provide some response. A szimulációhoz hasonlóan a metódus logikáját egy JavaScript-fájlban tárolja a rendszer, és az eszköz állapota is használható.Similarly to the simulation, the method logic is stored in a JavaScript file, and can interact with the device state. Például:For example:

"CloudToDeviceMethods": {
    "Start": {
        "Type": "JavaScript",
        "Path": "release-pressure.js"
    }
}

Eszköz-definíciós fájl létrehozásaCreate a device definition file

Ebben a útmutatóban megtudhatja, hogyan hozhat létre egy eszköz modellt a drone számára.In this how-to-guide you see how to create a device model for a drone. A drone véletlenszerűen veszi körül a koordinátákat a hely és a magasság beállításával.The drone will randomly fly around an initial set of coordinates changing location and altitude.

Másolja a következő JSON-t egy szövegszerkesztőbe, és mentse drone.jsként.Copy the following JSON into a text editor and save it as drone.json.

Eszköz-definíció JSON-példaDevice definition JSON example

{
  "SchemaVersion": "1.0.0",
  "Id": "drone",
  "Version": "0.0.1",
  "Name": "Drone",
  "Description": "Simple drone.",
  "Protocol": "AMQP",
  "Simulation": {
    "InitialState": {
      "velocity": 0.0,
      "velocity_unit": "mm/sec",
      "acceleration": 0.0,
      "acceleration_unit": "mm/sec^2",
      "latitude": 47.476075,
      "longitude": -122.192026,
      "altitude": 0.0
    },
    "Interval": "00:00:05",
    "Scripts": [{
      "Type": "JavaScript",
      "Path": "drone-state.js"
    }]
  },
  "Properties": {
    "Type": "Drone",
    "Firmware": "1.0",
    "Model": "P-96"
  },
  "Tags": {
    "Owner": "Contoso"
  },
  "Telemetry": [{
      "Interval": "00:00:05",
      "MessageTemplate": "{\"velocity\":\"${velocity}\",\"acceleration\":\"${acceleration}\",\"position\":\"${latitude}|${longitude}|${altitude}\"}",
      "MessageSchema": {
        "Name": "drone-event-sensor;v1",
        "Format": "JSON",
        "Fields": {
          "velocity": "double",
          "velocity_unit": "text",
          "acceleration": "double",
          "acceleration_unit": "text",
          "latitude": "double",
          "longitude": "double",
          "altitude": "double"
        }
      }
    }
  ],
    "CloudToDeviceMethods": {
        "RecallDrone": {
            "Type": "JavaScript",
            "Path": "droneRecall-method.js"
        }
    }
}

Viselkedési parancsfájlok fájljaiBehavior script files

A viselkedési parancsfájlban található kód a dronet helyezi át.The code in the behavior script file moves the drone. A szkript megváltoztatja a drone jogosultságszint-emelését és helyét az eszköz memóriájában lévő állapotának módosításával.The script alters the drone's elevation and location by manipulating the device's in memory state.

A JavaScript-fájloknak rendelkeznie kell egy függvénnyel, amely két paramétert fogad el:The JavaScript files must have a main function, that accepts two parameters:

  • Három tulajdonságot tartalmazó környezeti objektum:A context object that contains three properties:
    • a currentTime az éééé-hh-dd'T'HH: PP: sszzz karakterlánc formátumban kell megadni.currentTime as a string with format yyyy-MM-dd'T'HH:mm:sszzz.
    • deviceId.deviceId. Példa: szimulált. lift. 123.For example, Simulated.Elevator.123.
    • deviceModel.deviceModel. Például: lift.For example, Elevator.
  • Egy állapot -objektum, amely az előző hívás függvényében visszaadott érték.A state object that's the value returned by the function in the previous call. Az eszköz állapotát a szimulációs szolgáltatás tartja karban, és telemetria-üzenetek létrehozásához használja.This device state is maintained by the simulation service, and used to generate telemetry messages.

A függvény az új eszköz állapotát adja vissza.The main function returns the new device state. Például:For example:

function main(context, state) {

    // Use context if the simulation depends on
    // time or device details.
    // Execute some logic, updating 'state'

    return state;
}

Viselkedési parancsfájl létrehozásaCreate a behavior script file

Másolja a következő JavaScriptet egy szövegszerkesztőbe, és mentse drone-state.jsként.Copy the following JavaScript into a text editor and save it as drone-state.js.

Példa az eszköz modell JavaScript-szimulációraDevice model JavaScript simulation example

"use strict";

// Position control
const DefaultLatitude = 47.476075;
const DefaultLongitude = -122.192026;
const DistanceVariation = 10;

// Altitude control
const DefaultAltitude = 0.0;
const AverageAltitude = 499.99;
const AltitudeVariation = 5;

// Velocity control
const AverageVelocity = 60.00;
const MinVelocity = 20.00;
const MaxVelocity = 120.00;
const VelocityVariation = 5;

// Acceleration control
const AverageAcceleration = 2.50;
const MinAcceleration = 0.01;
const MaxAcceleration = 9.99;
const AccelerationVariation = 1;

// Display control for position and other attributes
const GeoSpatialPrecision = 6;
const DecimalPrecision = 2;

// Default state
var state = {
    velocity: 0.0,
    velocity_unit: "mm/sec",
    acceleration: 0.0,
    acceleration_unit: "mm/sec^2",
    latitude: DefaultLatitude,
    longitude: DefaultLongitude,
    altitude: DefaultAltitude
};

// Default device properties
var properties = {};

/**
 * Restore the global state using data from the previous iteration.
 *
 * @param previousState device state from the previous iteration
 * @param previousProperties device properties from the previous iteration
 */
function restoreSimulation(previousState, previousProperties) {
    // If the previous state is null, force a default state
    if (previousState) {
        state = previousState;
    } else {
        log("Using default state");
    }

    if (previousProperties) {
        properties = previousProperties;
    } else {
        log("Using default properties");
    }
}

/**
 * Simple formula generating a random value around the average
 * in between min and max
 */
function vary(avg, percentage, min, max) {
    var value = avg * (1 + ((percentage / 100) * (2 * Math.random() - 1)));
    value = Math.max(value, min);
    value = Math.min(value, max);
    return value;
}

/**
 * Entry point function called by the simulation engine.
 * Returns updated simulation state.
 * Device property updates must call updateProperties() to persist.
 *
 * @param context             The context contains current time, device model and id
 * @param previousState       The device state since the last iteration
 * @param previousProperties  The device properties since the last iteration
 */
/*jslint unparam: true*/
function main(context, previousState, previousProperties) {

    // Restore the global state before generating the new telemetry, so that
    // the telemetry can apply changes using the previous function state.
    restoreSimulation(previousState, previousProperties);

    state.acceleration = vary(AverageAcceleration, AccelerationVariation, MinAcceleration, MaxAcceleration).toFixed(DecimalPrecision);
    state.velocity = vary(AverageVelocity, VelocityVariation, MinVelocity, MaxVelocity).toFixed(DecimalPrecision);

    // Use the last coordinates to calculate the next set with a given variation
    var coords = varylocation(Number(state.latitude), Number(state.longitude), DistanceVariation);
    state.latitude = Number(coords.latitude).toFixed(GeoSpatialPrecision);
    state.longitude = Number(coords.longitude).toFixed(GeoSpatialPrecision);

    // Fluctuate altitude between given variation constant by more or less
    state.altitude = vary(AverageAltitude, AltitudeVariation, AverageAltitude - AltitudeVariation, AverageAltitude + AltitudeVariation).toFixed(DecimalPrecision);

    return state;
}

/**
 * Generate a random geolocation at some distance (in miles)
 * from a given location
 */
function varylocation(latitude, longitude, distance) {
    // Convert to meters, use Earth radius, convert to radians
    var radians = (distance * 1609.344 / 6378137) * (180 / Math.PI);
    return {
        latitude: latitude + radians,
        longitude: longitude + radians / Math.cos(latitude * Math.PI / 180)
    };
}

Metódus parancsfájl-fájljának létrehozásaCreate a method script file

A metódus parancsfájljai hasonlók a viselkedési parancsfájlokhoz.Method scripts are similar to behavior scripts. Definiálják az eszköz viselkedését, amikor egy adott felhőt az eszköz metódusának hívnak.They define the device behavior when a specific cloud to device method is called.

A drone-visszahívás parancsfájl beállítja a drone koordinátáit egy rögzített pontra, hogy szimulálja a hazai hazatérést.The drone recall script sets the drone's coordinates to a fixed point to simulate the drone returning home.

Másolja a következő JavaScriptet egy szövegszerkesztőbe, és mentse droneRecall-method.jsként.Copy the following JavaScript into a text editor and save it as droneRecall-method.js.

Példa az eszköz modell JavaScript-szimulációraDevice model JavaScript simulation example

"use strict";

// Default state
var state = {
    velocity: 0.0,
    velocity_unit: "mm/sec",
    acceleration: 0.0,
    acceleration_unit: "mm/sec^2",
    latitude: 0.0,
    longitude: 0.0,
    altitude: 0.0
};

// Default device properties
var properties = {};

/**
 * Restore the global state using data from the previous iteration.
 *
 * @param previousState device state from the previous iteration
 * @param previousProperties device properties from the previous iteration
 */
function restoreSimulation(previousState, previousProperties) {
    // If the previous state is null, force a default state
    if (previousState) {
        state = previousState;
    } else {
        log("Using default state");
    }

    if (previousProperties) {
        properties = previousProperties;
    } else {
        log("Using default properties");
    }
}

/**
 * Entry point function called by the simulation engine.
 *
 * @param context        The context contains current time, device model and id, not used
 * @param previousState  The device state since the last iteration, not used
 * @param previousProperties  The device properties since the last iteration
 */
/*jslint unparam: true*/
function main(context, previousState, previousProperties) {

    // Restore the global device properties and the global state before
    // generating the new telemetry, so that the telemetry can apply changes
    // using the previous function state.
    restoreSimulation(previousState, previousProperties);

    //simulate the behavior of a drone when recalled
  state.latitude = 47.476075;
  state.longitude = -122.192026;
  return state;
}

Parancsfájlok hibakereséseDebugging script files

Habár nem csatolhat hibakeresőt egy futó viselkedési fájlhoz, a log függvénnyel adatokat írhat a szolgáltatás naplójába.While you can't attach a debugger to a running behavior file, it's possible to write information to the service log using the log function. Szintaktikai hibák esetén a tolmács meghibásodik, és a kivételre vonatkozó adatokat ír a naplóba.For syntax errors, the interpreter fails and writes information about the exception to the log.

Naplózási példa:Logging example:

function main(context, state) {

    log("This message will appear in the service logs.");

    log(context.deviceId);

    if (typeof(state) !== "undefined" && state !== null) {
        log("Previous value: " + state.temperature);
    }

    // ...

    return updateState;
}

Speciális eszköz modell üzembe helyezéseDeploy an advanced device model

A speciális eszköz modell üzembe helyezéséhez töltse fel az eszköz szimulációs példányának fájljait:To deploy your advanced device model, you upload the files your Device Simulation instance:

A menüsávon válassza az Eszközmodellek gombot.Select Device models in the menu bar. Az eszközök modelljei lap az eszköz-szimuláció ezen példányában elérhető modelleket sorolja fel:The Device models page lists the device models available in this instance of Device Simulation:

Eszközmodellek

Kattintson az + Eszközmodellek hozzáadása elemre a lap jobb felső sarkában:Click + Add Device Models in the top right corner of the page:

Eszközmodell hozzáadása

Kattintson a speciális elemre a speciális eszköz modell lapjának megnyitásához:Click Advanced to open the advanced device model tab:

Speciális lap

Kattintson a Tallózás gombra, és válassza ki a létrehozott JSON-és JavaScript-fájlokat.Click Browse and select the JSON and JavaScript files you created. Ügyeljen arra, hogy mindhárom fájlt kiválassza.Be sure to select all three files. Ha egy fájl hiányzik, az érvényesítés sikertelen lesz:If any one file is missing, validation fails:

Fájlok tallózása

Ha a fájlok ellenőrzése sikeres, kattintson a Save (Mentés ) gombra, és az eszköz modellje készen áll a szimulációban való használatra.If your files pass validation, click Save and your device model is ready to be used in a simulation. Ellenkező esetben javítsa ki a hibákat, és töltse fel újra a fájlokat:Otherwise, fix any errors and reupload the files:

Mentés

Következő lépésekNext steps

Ebben a útmutatóban megismerte az eszköz-szimulációban használt eszköz-modell fájljait, valamint a speciális eszköz modell létrehozását.In this how-to guide, you learned about the device model files used in Device Simulation and how to create an advanced device model. Következő lépésként érdemes megvizsgálni, hogyan használhatók a Time Series Insights az eszköz-szimulációs megoldás-gyorssegédből eljuttatott telemetria megjelenítéséhez.Next, you may want to explore how to Use Time Series Insights to visualize telemetry sent from the Device Simulation solution accelerator.