BACnetStack_AddNetworkPortObject

bool BACnetStack_AddNetworkPortObject(
  const uint32_t deviceInstance,
  const uint32_t objectInstance,
  const uint8_t networkType,
  const uint8_t protocolLevel,
  const uint16_t networkNumber,
  const uint8_t networkNumberQuality,
  const uint32_t referencePort);

Adds a BACnet Network Port Object.

The device must be added first before this function can be called.

Network_Number and Network_Number_Quality apply ONLY when protocolLevel is BACNET_APPLICATION. Table 12-71.2 marks them required in that column alone, and this function enables them only there - so on a PHYSICAL or PROTOCOL port the networkNumber and networkNumberQuality arguments are accepted and then ignored, and reading either property returns Error(PROPERTY, UNKNOWN_PROPERTY).

WHICH PROPERTIES EXIST depends on networkType and protocolLevel - ASHRAE 135-2024 Table 12-71 plus the sub-table for the network type and the column for the protocol level. The table below covers the common case, networkType = IPV4 with protocolLevel = BACNET_APPLICATION; summaries of the other supported combinations follow it. ARCNET, PTP, LONTALK, ZIGBEE and SERIAL are NOT implemented: this function returns false for them. IPV6 needs a build with STACK_OPTION_DATA_LINK_LAYER_IPV6.

Network Port differs from every other object type in this API in one important way: for most of its properties the stack tries a registered Get callback FIRST and falls back to its own stored value, so an application MAY override a stack-held value. The exceptions - MAC_Address, APDU_Length, Network_Number, Changes_Pending and the BACnet/SC properties - are answered by the stack unconditionally and cannot be overridden. FD_BBMD_Address is the application’s when it serves it (see (***) below), and otherwise the stack’s own foreign-device registration.

Handled and stored by the CAS BACnet Stack (a Get callback, if registered, wins, except for Network_Number and Changes_Pending, which the stack always serves itself):

• Network_Type, Protocol_Level, Reference_Port (all set by this function)
• Network_Number (never overridable) and Network_Number_Quality (both set by this function). A Network_Number written by a client is held pending (135-2024 cl. 12.56.13): reads return the written value and Changes_Pending reads TRUE, while routing and Network_Number_Quality keep the value in use, until a ReinitializeDevice ACTIVATE_CHANGES or WARMSTART, or BACnetStack_ActivateNetworkPortPendingChanges(), activates it. The new value is handed to CallbackSetPropertyUnsignedInteger at activation, not at the write. The write is refused with an Abort unless both CallbackSetPropertyUnsignedInteger and CallbackReinitializeDevice are registered. No Get callback is asked for Network_Number or Changes_Pending: the stack serves both itself, pending or not.
• BACnet_IP_Mode: NORMAL, BBMD once BACnetStack_SetBBMD() succeeds, FOREIGN while this port holds a foreign-device registration
• Changes_Pending (never overridable): TRUE while a written or You-Are-assigned value waits to be activated by ReinitializeDevice, otherwise FALSE
• Command: present and writable on every Network Port this function creates, and always reads IDLE. DISCARD_CHANGES is executed on every port; the other commands, and the host’s part in them, are described at BACnetStack_RegisterCallbackNetworkPortCommand()
• Routing_Table: in a build with STACK_OPTION_ROUTER_PHYSICAL, enabled and refreshed by the stack on every BACnetStack_Tick() while this device’s physical router is enabled. A device that is only a virtual router has no Routing_Table
• Object_Identifier, Object_Type, Status_Flags, Property_List

Generated by the stack and NOT overridable by any callback:

• APDU_Length - 1476 for IPV4 / ETHERNET / VIRTUAL / SC, 480 for MSTP
• MAC_Address - for IPV4 + BACNET_APPLICATION this is READ-ONLY and derived from IP_Address and BACnet_IP_UDP_Port (cl. 12.56.19), so it is served indirectly by those two callbacks. For MSTP it comes from CallbackGetPropertyOctetString (exactly one octet); while a MAC that a matching You-Are assigned is pending, reads serve that value instead. For BACnet/SC it comes from stack SC state.

Callbacks are used to handle the other properties. The following list contains those properties for networkType = IPV4, protocolLevel = BACNET_APPLICATION, and the Callbacks that are used to get the required data:

    --------------------------------------------------------------------------------
    Property            Datatype            Callback
    --------------------------------------------------------------------------------
    ObjectName          CharacterString     CallbackGetPropertyCharacterString
                                            CallbackSetPropertyCharacterString
                                            (only if made writable)
    Reliability*        Enumerated          CallbackGetPropertyEnumerated
    OutOfService        Boolean             CallbackGetPropertyBool
                                            CallbackSetPropertyBool
    IPAddress           OctetString         CallbackGetPropertyOctetString
                                            CallbackSetPropertyOctetString
    IPSubnetMask        OctetString         CallbackGetPropertyOctetString
                                            CallbackSetPropertyOctetString
    IPDefaultGateway    OctetString         CallbackGetPropertyOctetString
                                            CallbackSetPropertyOctetString
    IPDNSServer**       OctetString array   CallbackGetPropertyUnsignedInteger
                                            CallbackGetPropertyOctetString
    BACnetIPUDPPort     Unsigned            CallbackGetPropertyUnsignedInteger
                                            CallbackSetPropertyUnsignedInteger
    LinkSpeed           Real                CallbackGetPropertyReal
    FDBBMDAddress***    BACnetHostNPort     CallbackGetPropertyEnumerated
                                            CallbackGetPropertyUnsignedInteger
                                            CallbackGetPropertyOctetString
                                            CallbackGetPropertyCharacterString
    FDSubscriptionLifetime****
                        Unsigned            CallbackGetPropertyUnsignedInteger
                                            CallbackSetPropertyUnsignedInteger
    --------------------------------------------------------------------------------
    (*)    Served by the stack's intrinsic alarm engine instead, if intrinsic reporting has been
         enabled for this object.
    (**)   An array: the stack calls CallbackGetPropertyUnsignedInteger with array index 0 for
         the element count, then CallbackGetPropertyOctetString per element.  If
         CallbackGetPropertyUnsignedInteger is not registered, or declines the element-count
         read, the property reads as a one-entry array holding X'00000000', which 135-2024
         12.56.31 defines as "not available or is not configured".
    (***)  Assembled from several calls, all against propertyIdentifier FD_BBMD_Address:
         CallbackGetPropertyEnumerated with no array index returns the host type
         (0 = none, 1 = ip-address, 2 = name); CallbackGetPropertyUnsignedInteger with array
         index 2 returns the port; then array index 1 returns the host - via
         CallbackGetPropertyOctetString for an IP address, or
         CallbackGetPropertyCharacterString for a name.  Without CallbackGetPropertyEnumerated,
         or when it declines without naming an error code, the stack answers from this port's own
         foreign-device registration, or with the not-configured value when there is none.
         A client's write is held pending: a written value not yet activated reads as written,
         and it is handed to the matching Set callbacks only at activation (ReinitializeDevice
         ACTIVATE_CHANGES or WARMSTART, or BACnetStack_ActivateNetworkPortPendingChanges()), not
         at the write.  The write is refused with an Abort unless CallbackSetPropertyUnsignedInteger
         and the Set callback for the written host type (CallbackSetPropertyNull for none,
         CallbackSetPropertyOctetString for an IP address, CallbackSetPropertyCharacterString for a
         name) are registered, and unless the change can be activated: CallbackReinitializeDevice
         registered, in a build with STACK_OPTION_REINITIALIZE_DEVICE.
    (****) If the application does not answer the read: when the stack itself holds a foreign
         device registration for this port, the time-to-live of that registration; otherwise
         0.  A callback that declines and names an error code returns that error.  A client's
         write is held pending: it is handed to CallbackSetPropertyUnsignedInteger only at
         activation (ReinitializeDevice ACTIVATE_CHANGES or WARMSTART, or
         BACnetStack_ActivateNetworkPortPendingChanges()), not at the write, and is refused with
         an Abort unless CallbackSetPropertyUnsignedInteger and CallbackReinitializeDevice are
         both registered (the latter in a build with STACK_OPTION_REINITIALIZE_DEVICE).
    --------------------------------------------------------------------------------

Other supported networkType / protocolLevel combinations:

• IPV4 + PROTOCOL: as above but without BACnet_IP_Mode, BACnet_IP_UDP_Port, Network_Number, Network_Number_Quality, APDU_Length and the foreign-device properties. PHYSICAL and NON_BACNET_APPLICATION are rejected.
• ETHERNET: PHYSICAL only. Reference_Port, MAC_Address, Link_Speed. Every other protocol level is rejected.
• MSTP: BACNET_APPLICATION only. Reference_Port, Max_Manager and Max_Info_Frames (always writable; a client’s write is held pending and handed to CallbackSetPropertyUnsignedInteger at activation, as for FD_Subscription_Lifetime), MAC_Address, Network_Number, Network_Number_Quality, APDU_Length.
• VIRTUAL: any protocol level. Reference_Port and MAC_Address always; BACNET_APPLICATION adds Network_Number, Network_Number_Quality, APDU_Length.
• IPV6 (requires the BACnet/IPv6 data link): BACNET_APPLICATION only. The Table 12-71.4 properties; MAC_Address is the 3-octet VMAC. BACnet_IPv6_Mode, FD_BBMD_Address, FD_Subscription_Lifetime and (with STACK_OPTION_BVLL_BBMD) BBMD_Broadcast_Distribution_Table and BBMD_Accept_FD_Registrations are writable, held by the stack (never asked of a callback) and handed to the data link at activation; BBMD_Foreign_Device_Table is read from the data link. No export configures the IPv6 BBMD or foreign device directly yet.
• SECURE_CONNECT (requires the BACnet/SC data link): BACNET_APPLICATION enables Reference_Port, Out_Of_Service (writable), Network_Number, Network_Number_Quality, APDU_Length, MAC_Address, Max_BVLC_Length_Accepted, Max_NPDU_Length_Accepted, SC_Primary_Hub_URI, SC_Failover_Hub_URI, SC_Minimum_Reconnect_Time, SC_Maximum_Reconnect_Time, SC_Connect_Wait_Timeout, SC_Disconnect_Wait_Timeout, SC_Heartbeat_Timeout (all writable), Operational_Certificate_File, Issuer_Certificate_Files, Certificate_Signing_Request_File and SC_Hub_Connector_State. ALL of these are stored and served by the stack and are NOT callback-overridable. Current_Health and the SC connection-status properties are deliberately left for the application to enable.

Note

Requires the STACK_OPTION_OBJECT_TYPE_NETWORK_PORT build option.

See also: BACnetStack_ObjectExists(), BACnetStack_RemoveObject()

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.56 (Network Port Object Type).

Parameters

Parameter	Direction	Description
deviceInstance	in	The instance number of the device that owns this Network Port object.
objectInstance	in	The instance number of this Network Port object. Must be between 0 and 4194302 inclusively (22 bits). 4194303 is the reserved “unknown instance” value and is rejected. Use each Network Port instance number on only one device, across every device this stack hosts (virtual devices included): the send and receive callbacks and the per-port exports name a port by its instance alone, so a second device’s port with the same instance can be sent and received through the first one’s data link. The stack does not refuse a repeat.
networkType	in	The kind of network that this Network Port object stands for (cl. 12.56.9). See CASBACnetStack::BACnetNetworkType for available values.
protocolLevel	in	The protocol level for this Network Port object. See CASBACnetStack::BACnetProtocolLevel for available values.
networkNumber	in	The network number for this Network Port object.
networkNumberQuality	in	The quality of the network number for this Network Port object: 0 = UNKNOWN, 1 = LEARNED, 2 = LEARNED_CONFIGURED, 3 = CONFIGURED. Values above CONFIGURED are rejected. See CASBACnetStack::BACnetNetworkNumberQuality.
referencePort	in	the instance of whichever Network Port object sits directly beneath this one in the protocol stack (cl. 12.56.11). If this is the lowest protocol layer, use 4194303. A value above 4194303 is not a Network Port instance number and is refused: the call returns false and changes nothing.

Returns

True if successful, false if failed. Adding an instance that is already a Network Port object of a different networkType is refused: it returns false and changes nothing. A virtual device already has the virtual-network Network Port its gateway created for it. Adding an existing instance with the same networkType succeeds and keeps the object as it is. A BACnet/IP Network Port at the BACnet application level records its data link’s own address and mask from IP_Address, BACnet_IP_UDP_Port and IP_Subnet_Mask, read through the Get callbacks, when it is added. It reads them again when CallbackGetPropertyOctetString or CallbackGetPropertyUnsignedInteger is registered, provided CallbackGetPropertyOctetString is registered. To pick up a changed address later, call this function again for that port.

Topic: Objects and properties. Declared in CASBACnetStackDLL.h.