Channel basics

Every MasterChannel works the same way once it's created, whatever its transport. This page covers what they share; the following pages cover what's specific to each transport.

Configuration

A MasterChannelConfig holds the settings every channel has: the master's address (different channels can use different addresses), the initial decode level for logging, and the buffer sizes. Increase the receive buffer only if an outstation sends larger fragments than usual. The response timeout is set for each association, in its AssociationConfig.

Rust

fn get_master_channel_config(
    master_address: EndpointAddress,
) -> Result<MasterChannelConfig, Box<dyn std::error::Error>> {
    let mut config = MasterChannelConfig::new(master_address);
    config.decode_level = AppDecodeLevel::ObjectValues.into();
    Ok(config)
}

C

dnp3_master_channel_config_t get_master_channel_config(void)
{
    dnp3_master_channel_config_t config = dnp3_master_channel_config_init(MASTER_ADDRESS);
    config.decode_level.application = DNP3_APP_DECODE_LEVEL_OBJECT_VALUES;
    return config;
}

C++

dnp3::MasterChannelConfig config(MASTER_ADDRESS);
config.decode_level.application = dnp3::AppDecodeLevel::object_values;

Java

private static MasterChannelConfig getMasterChannelConfig() {
  MasterChannelConfig config = new MasterChannelConfig(ushort(MASTER_ADDRESS));
  config.decodeLevel.application = AppDecodeLevel.OBJECT_VALUES;
  return config;
}

C#

private static MasterChannelConfig GetMasterChannelConfig()
{
    return new MasterChannelConfig(MasterAddress)
        .WithDecodeLevel(DecodeLevel.Nothing().WithApplication(AppDecodeLevel.ObjectValues));
}

Enabling

A channel doesn't communicate until you call enable, so you can add its associations and polls first. Call disable to stop communicating without losing them.

Lifetime

Keep the channel for as long as it should run. In Java and .NET, a channel shuts down when it's garbage collected, so keep a reference to it, and shut it down yourself when you're done. In C and C++, destroying it shuts it down. In Rust, it runs until the MasterChannel and every AssociationHandle created from it are dropped.

Logging at runtime

set_decode_level changes how much of the protocol traffic a running channel logs, for example to debug a site without restarting. See Logging.

Link errors

The LinkErrorMode chosen when creating a TCP or TLS channel decides what happens when the master receives a malformed link-layer frame. TCP doesn't lose data, so Close is the usual choice; Discard treats the connection like a serial port. Serial channels always discard.

State listeners

A listener reports the state of the channel's connection or port, for example to show it on a status screen:

Transport	Listener
TCP and TLS clients	ClientStateListener
Serial	PortStateListener