Device Attributes

The master API can be used to READ and WRITE objects from Group 0. Attribute values, including attribute lists (g0v255s), are passed to the ReadHandler when they are received from the outstation.

Reading Attributes

A request to read attributes use the READ function code combined with one or more object headers. Each header consists of a group 0 variation using the 8-bit start/stop qualifier code (0x00). The point index in the request corresponds to the "set" to which the device attribute belongs.

Rust

let result = association
    .read(ReadRequest::device_attribute(
        AllAttributes,
        AttrSet::Default,
    ))
    .await;

if let Err(err) = result {
    tracing::warn!("error: reading device attributes {}", err);
}

C

dnp3_request_t *request = dnp3_request_create();
dnp3_request_add_specific_attribute(request, DNP3_ATTRIBUTE_VARIATIONS_ALL_ATTRIBUTES_REQUEST, 0);

dnp3_read_task_callback_t cb = {
    .on_complete = &on_read_success,
    .on_failure = &on_read_failure,
    .on_destroy = NULL,
    .ctx = NULL,
};

dnp3_master_channel_read(channel, association_id, request, cb);
dnp3_request_destroy(request);

C++

dnp3::Request request;
request.add_specific_attribute(dnp3::attribute_variations::all_attributes_request, 0);
channel.read(assoc, request, std::make_unique<ReadTaskCallback>());

Java

Request request = new Request();
request.addSpecificAttribute(AttributeVariations.ALL_ATTRIBUTES_REQUEST, ubyte(0));
channel.read(association, request).toCompletableFuture().get();

C#

var request = new Request();
request.AddSpecificAttribute(AttributeVariations.AllAttributesRequest, 0);
await channel.Read(association, request);

Writing Attributes

Attributes can be written one at a time or in batches by constructing a request header send it the outstation. The Rust API uses a single method to add an attribute to the header, whereas the bindings use a separate method for each type of attribute.

The example below demonstrates how to write g0v245 (User-assigned location) to the outstation which is a visible string.

Rust

let headers = Headers::default()
    .add_attribute(StringAttr::UserAssignedLocation.with_value("Mt. Olympus"));

let result = association
    .send_and_expect_empty_response(FunctionCode::Write, headers)
    .await;

if let Err(err) = result {
    tracing::warn!("error writing device attribute: {}", err);
}

C

dnp3_request_t *request = dnp3_request_create();
dnp3_request_add_string_attribute(request, DNP3_ATTRIBUTE_VARIATIONS_USER_ASSIGNED_LOCATION, 0, "Mt. Olympus");

dnp3_empty_response_callback_t cb = {
    .on_complete = &on_generic_success,
    .on_failure = &on_generic_failure,
    .on_destroy = NULL,
    .ctx = "write device attribute",
};
dnp3_master_channel_send_and_expect_empty_response(channel, association_id, DNP3_FUNCTION_CODE_WRITE, request, cb);
dnp3_request_destroy(request);

C++

dnp3::Request request;
request.add_string_attribute(dnp3::attribute_variations::user_assigned_location, 0, "Mt. Olympus");
channel.send_and_expect_empty_response(assoc, dnp3::FunctionCode::write, request, std::make_unique<GenericCallback>("write-device-attribute"));

Java

Request request = new Request();
request.addStringAttribute(AttributeVariations.USER_ASSIGNED_LOCATION, ubyte(0), "Mt. Olympus");
channel.sendAndExpectEmptyResponse(association, FunctionCode.WRITE, request).toCompletableFuture().get();

C#

var request = new Request();
request.AddStringAttribute(AttributeVariations.UserAssignedLocation, 0, "Mt. Olympus");
await channel.SendAndExpectEmptyResponse(association, FunctionCode.Write, request);