Overview

In this section, we’ll use cURL to read the list of groov I/O modules installed on a groov EPIC chassis.

Step 1 - Build the Request

To make the HTTP request, we need three basic pieces of information:

  • Hostname or IP Address of the groov EPIC processor
  • URL path of the request
  • The API key of a groov user with groov Manage permissions

In this example, we’ll use an example hostname opto-01-02-03 for the address, and an example API key of 3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo.

The URL path to get the list of modules is /manage/api/v1/io/local/modules/type. More information about it is in the API Reference.

Step 2 - Execute the Request

Combining the information from Step 1, the cURL request looks like this:

curl -k -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/io/local/modules/type

The -k flag is used to ignore any SSL errors. By default, groov EPIC processors use a self-signed SSL certificate, but your computer and cURL has no reference to it. To make these examples easier, we just ignore the issue with the -k flag. The requests will still be encrypted, but the certificate itself will not be verified.

The API key is set with the -H flag, which adds a custom HTTP header named “apiKey” to the request.

If you run the above command (adjusting for your own address and API key), the response should look like this:

{"types":[{"index":0,"type":"0x5000000F","name":"GRV-IAC-24"},{"index":1,"type":"0x90000012","name":"GRV-OAC-12"},{"index":2,"type":"0x60000002","name":"GRV-IV-24"},{"index":3,"type":"0xA0000003","name":"GRV-OVMALC-8"},{"index":4,"type":"0x00000000","name":""},{"index":5,"type":"0x00000000","name":""},{"index":6,"type":"0x00000000","name":""},{"index":7,"type":"0x00000000","name":""},{"index":8,"type":"0x5400000A","name":"GRV-IACIS-12"},{"index":9,"type":"0x94000019","name":"GRV-OMRIS-8"},{"index":10,"type":"0x00000000","name":""},{"index":11,"type":"0x00000000","name":""},{"index":12,"type":"0x00000000","name":""},{"index":13,"type":"0x00000000","name":""},{"index":14,"type":"0x00000000","name":""},{"index":15,"type":"0x00000000","name":""}]}

The response is a JSON object containing an array of module descriptions. If we pretty-print it, it’s much easier to read:

{
    "types": [
        {
        "index": 0,
        "type": "0x5000000F",
        "name": "GRV-IAC-24"
        },
        {
        "index": 1,
        "type": "0x90000012",
        "name": "GRV-OAC-12"
        },
        {
        "index": 2,
        "type": "0x60000002",
        "name": "GRV-IV-24"
        },
        {
        "index": 3,
        "type": "0xA0000003",
        "name": "GRV-OVMALC-8"
        },
        {
        "index": 4,
        "type": "0x00000000",
        "name": ""
        },
        
        ...etc...
        
    ]
}

For each module, the Type is given as a string version of the hexadecimal value of the module type ID. Each module type has a unique ID, which is a 32-bit unsigned number. For example, “0x5000000F” for GRV-IAC-24. If no module is plugged into a slot, then “id” will be “0x00000000”.

The name of the module is also given, such as “GRV-IAC-24” or “GRV-OVMALC-8”.

Other Module Information

The REST API has several URL endpoints for getting information about module and channel types.

The /api/v1/io/descriptions/modules/{module} endpoint can take either the module ID (e.g. “0x60000002”) or the module name (e.g. “GRV-IV-24”) and will return information about that type of module.

Using cURL and the module name, we can request it like this:

curl -k -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/io/descriptions/modules/GRV-IV-24

Or with the module ID:

curl -k -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/io/descriptions/modules/0x60000002

The response is:

{
    "schemaVersion": "1.0.0",
    "contentVersion": "1.0.4",
    "moduleId": "0x60000002",
    "productNumber": "GRV-IV-24",
    "numberOfChannels": 24,
    "productDescription": {
        "en": "Analog voltage input, 24 channels, 8 configurable input ranges from ±160 V to ±1.25 V"
    },
    "channelDescriptions": {
        "all": {
            "channelTypes": [
                "0x60000024",
                "0x6000000D",
                "0x6000000B",
                "0x6000000A",
                "0x60000017",
                "0x60000019",
                "0x60000025",
                "0x60000001"
            ],
            "defaultChannelType": "0x60000024"
        }
    },
    "productSpecification": {
        "en": {
            "Input Ranges": "±160.0 VDC, ±80.0 VDC, ±40.0 VDC, ±20.0 VDC, ±10.0 VDC, ±5.0 VDC, ±2.5 VDC, ±1.25 VDC",
            "Over-range limits": "±176.0 VDC, ±88.0 VDC, ±44.0 VDC, ±22.0 VDC, ±11.0 VDC, ±5.5 VDC, ±2.75 VDC, ±1.375 VDC",
            "Resolution": "Range / 1,048,576 (20-bits)",
            "Accuracy 0.1% of Range": "±160 mV, ±80 mV, ±40 mV, ±20 mV, ±10 mV, ±5 mV, ±2.5 mV, ±1.25 mV",
            "Gain Temperature Coefficient": "ppm/°C",
            "Offset Temperature Coefficient": "ppm/°C",
            "Input Impedance Nominal": "9.7 MOhms",
            "Input Filter": "-3 dB at 460 HZ",
            "Software Data Filtering, SMA ( simple moving average) and Weighted filter (Original)": "1 to 32 Readings,  moving average and (Original) 1 to 4096 Filter Weight",
            "Step Input Response Time": "277 ms x SMA value (8.8 s @ 32 SMA, Default SMA = 4 )",
            "Data Freshness / Update": "277 ms",
            "Analog Data Filtering": "-3 dB @ 2.4 Hz / -25 dB @ 60 Hz",
            "DC Common Mode Rejection": "> -120 dB",
            "AC Common Mode Rejection": "> -120 dB",
            "Max. Survivable Input": "300 V",
            "Max. Operating Common Mode Voltage": "250 V",
            "Problem Indications": "out of range",
            "Isolation (field-to-logic)": "300 V working, 1500 V transient (1 minute)",
            "Isolation (channel-to-channel)": "300V Between Zone A (ch 0–11) & Zone B (ch12–23)",
            "Number of Channels": "24",
            "Chassis Power Consumption": "1.0 W",
            "Connector": "28–14 AWG",
            "Torque, connector screw": "2.5 in-lb (0.28 N-m)",
            "Torque, hold-down screw": "3.5 in-lb (0.4 N-m)",
            "Temperature (operating)": "-20 °C to +70 °C",
            "Temperature (storage)": "-40 °C to +85 °C",
            "Relative Humidity (non-condensing)": "5–95%",
            "Agency Approvals": "UL/cUL(Class 1 Div. 2); CE, ATEX(Category 3, Zone 2), RoHS; DFARS; CB Scheme",
            "Warranty": "Lifetime"
        }
    }
}

Notice the value at channelDescriptions.channelTypes.channelTypes[0] is “0x60000024”

We can look up the 0x60000024 channel type with the /api/v1/io/descriptions/channels/{channelId} endpoint:

curl -k -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/io/descriptions/channels/0x60000024

Response:

{
    "channelTypeId": "0x60000024",
    "name": {
        "en": "±160V"
    },
    "engineeringUnits": "V",
    "minUnderScale": -177.6,
    "lowScale": -160,
    "highScale": 160,
    "maxOverScale": 177.6
}

From that response we can see that the normal operating scale is -160 to 160 V.

Next Step

Continue to reading and writing a digital channel.