Package org.openremote.agent.protocol.bluetooth.mesh

Class BaseMeshNetwork

java.lang.Object
org.openremote.agent.protocol.bluetooth.mesh.BaseMeshNetwork
Direct Known Subclasses:
MeshNetwork
public abstract class BaseMeshNetwork extends Object

  • Field Details

  • Method Details

    • createNetworkKey

      public NetworkKey createNetworkKey() throws IllegalArgumentException
      Creates an Network key
      Returns:
      NetworkKey
      Throws:
      IllegalArgumentException - in case the generated application key already exists

    • addNetKey

      public boolean addNetKey(NetworkKey newNetKey)
      Adds a Net key to the list of net keys with the given key index
      Parameters:
      newNetKey - Network key
      Throws:
      IllegalArgumentException - if the key already exists.

    • updateNetKey

      public boolean updateNetKey(NetworkKey networkKey, String newNetKey) throws IllegalArgumentException
      Update a network key with the given 16-byte hexadecimal string in the mesh network.

      Updating a NetworkKey's key value requires initiating a Key Refresh Procedure. A NetworkKey that's in use would require a Key Refresh Procedure to update it's key contents. However a NetworkKey that's not in could be updated without this procedure. If the key is in use, call distributeNetKey(NetworkKey, byte[]) to initiate the Key Refresh Procedure.

      Parameters:
      networkKey - Network key
      newNetKey - 16-byte hexadecimal string
      Throws:
      IllegalArgumentException - if the key is already in use

    • updateNetKey

      public boolean updateNetKey(NetworkKey networkKey) throws IllegalArgumentException
      Update a network key in the mesh network.

      Updating a NetworkKey's key value requires initiating a Key Refresh Procedure. A NetworkKey that's in use would require a Key Refresh Procedure to update it's key contents. However a NetworkKey that's not in could be updated without this procedure. If the key is in use, call distributeNetKey(NetworkKey, byte[]) to initiate the Key Refresh Procedure.

      Parameters:
      networkKey - Network key
      Throws:
      IllegalArgumentException - if the key is already in use

    • distributeNetKey

      public NetworkKey distributeNetKey(NetworkKey networkKey, byte[] newNetKey) throws IllegalArgumentException
      Distribute Net Key will start the key refresh procedure and return the newly updated key.

      This process contains three phases. NetworkKey.KEY_DISTRIBUTION - Distribution of the new Keys distributeNetKey(NetworkKey, byte[]). NetworkKey.USING_NEW_KEYS - Switching to the new keys switchToNewKey(NetworkKey). NetworkKey.REVOKE_OLD_KEYS - Revoking old keys revokeOldKey(NetworkKey). The new key is distributed to the provisioner node by setting the currently used key as the old key and setting the currently used key to the new key value. This will change the phase of the network key toNetworkKey.KEY_DISTRIBUTION. During this phase a node will transmit using the old key but may receive using both old and the new key. After a successful distribution to the provisioner, the user may start sending ConfigNetKeyUpdate messages to the respective nodes in the network that requires updating. In addition if the user wishes to update the AppKey call distributeAppKey(ApplicationKey, byte[]) to update the Application Key on the provisioner and then distribute it to other nodes by sending ConfigAppKeyUpdate to update an AppKey. However it shall be only successfully processed if the NetworkKey bound to the Application Key is in NetworkKey.KEY_DISTRIBUTION and the received app key value is different or when the received AppKey value is the same as previously received value. Also note that sending a ConfigNetKeyUpdate during NetworkKey.NORMAL_OPERATION will switch the phase to NetworkKey.KEY_DISTRIBUTION. Once distribution is completed, call switchToNewKey(NetworkKey) and send ConfigKeyRefreshPhaseSet to other nodes.

      Parameters:
      networkKey - Network key
      newNetKey - 16-byte key
      Throws:
      IllegalArgumentException - the key value is already in use.

    • switchToNewKey

      public boolean switchToNewKey(NetworkKey networkKey) throws IllegalArgumentException
      Switches the new key, this will initiate the provisioner node transmitting messages using the new keys but will support receiving messages using both old and the new key.

      This must be called after distributeNetKey(NetworkKey, byte[])

      Parameters:
      networkKey - Network key to switch too
      Returns:
      true if success or false otherwise
      Throws:
      IllegalArgumentException - if the provided key is not the same as the distributed key.

    • revokeOldKey

      public boolean revokeOldKey(NetworkKey networkKey)
      Revokes the old key.

      This initiates NetworkKey.REVOKE_OLD_KEYS of the Key Refresh Procedure in which user must send ConfigKeyRefreshPhaseSet message with transition set to NetworkKey.REVOKE_OLD_KEYS to the other nodes going through the Key Refresh Procedure. The library at this point will set the given Network Key's Phase to NetworkKey.NORMAL_OPERATION.

      Parameters:
      networkKey - Network key that was distributed
      Returns:
      true if success or false otherwise

    • removeNetKey

      public boolean removeNetKey(NetworkKey networkKey) throws IllegalArgumentException
      Removes a network key from the network key list
      Parameters:
      networkKey - key to be removed
      Throws:
      IllegalArgumentException - if the key is in use or if it does not exist in the list of keys

    • getNetKey

      public NetworkKey getNetKey(int keyIndex)
      Returns an application key with a given key index
      Parameters:
      keyIndex - index

    • createAppKey

      public ApplicationKey createAppKey() throws IllegalArgumentException
      Creates an application key
      Returns:
      ApplicationKey
      Throws:
      IllegalArgumentException - in case the generated application key already exists

    • addAppKey

      public boolean addAppKey(ApplicationKey newAppKey)
      Adds an app key to the list of keys with the given key index. If there is an existing key with the same index, an illegal argument exception is thrown.
      Parameters:
      newAppKey - application key
      Throws:
      IllegalArgumentException - if app key already exists

    • getAppKey

      public ApplicationKey getAppKey(int keyIndex)
      Returns an application key with a given key index
      Parameters:
      keyIndex - index

    • getAppKeys

      protected List<ApplicationKey> getAppKeys(int boundNetKeyIndex)
      Returns a list of application keys bound to a Network key
      Parameters:
      boundNetKeyIndex - Network Key index

    • updateAppKey

      public boolean updateAppKey(ApplicationKey applicationKey, String newAppKey) throws IllegalArgumentException
      Updates an app key with a given key in the mesh network.

      Updates the Key if it is not use, if not Updating a Key's key value requires initiating a Key Refresh Procedure. This requires the bound NetworkKey of the AppKey to be updated. A NetworkKey that's in use would require a Key Refresh Procedure to update it's key contents. However a NetworkKey that's not in could be updated without this procedure. If the key is in use, call distributeNetKey(NetworkKey, byte[]) to initiate the Key Refresh Procedure.

      Parameters:
      applicationKey - ApplicationKey
      newAppKey - Application key
      Throws:
      IllegalArgumentException - if the key is in use.

    • updateAppKey

      public boolean updateAppKey(ApplicationKey applicationKey) throws IllegalArgumentException
      Updates an app key in the mesh network.

      Updates the Key if it is not use, if not Updating a Key's key value requires initiating a Key Refresh Procedure. This requires the bound NetworkKey of the AppKey to be updated. A NetworkKey that's in use would require aKey Refresh Procedure to update it's key contents. However a NetworkKey that's not in could be updated without this procedure. If the key is in use, call distributeNetKey(NetworkKey, byte[]) to initiate the Key Refresh Procedure. After distributing the NetworkKey bound to the Application Key, user may call distributeAppKey(ApplicationKey, byte[]) to update the corresponding ApplicationKey.

      Parameters:
      applicationKey - ApplicationKey
      Throws:
      IllegalArgumentException - if the key is already in use

    • distributeAppKey

      public ApplicationKey distributeAppKey(ApplicationKey applicationKey, byte[] newAppKey) throws IllegalArgumentException
      Distributes/updates the provisioner node's the application key and returns the updated Application Key.

      This will only work if the NetworkKey bound to this ApplicationKey is in Phase 1 of the Key Refresh Procedure. Therefore the NetworkKey must be updated first before updating it's bound application key. Call distributeNetKey(NetworkKey, byte[]) to initiate the Key Refresh Procedure to update a Network Key that's in use by the provisioner or the nodes, if it has not been started already. To update a key that's not in use call updateAppKey(ApplicationKey, String)

      Once the provisioner nodes' AppKey is updated user must distribute the updated AppKey to the nodes. This can be done by sending ConfigAppKeyUpdate message with the new key.

      Parameters:
      applicationKey - Network key
      newAppKey - 16-byte key
      Throws:
      IllegalArgumentException - the key value is already in use.

    • removeAppKey

      public boolean removeAppKey(ApplicationKey appKey) throws IllegalArgumentException
      Removes an app key from the app key list
      Parameters:
      appKey - app key to be removed
      Throws:
      IllegalArgumentException - if the key is in use or if it does not exist in the list of keys

    • isKeyInUse

      public boolean isKeyInUse(org.openremote.agent.protocol.bluetooth.mesh.MeshKey meshKey)
      Checks if the app key is in use.

      This will check if the specified app key is added to a node other than the selected provisioner node

      Parameters:
      meshKey - MeshKey

    • createProvisioner

      public Provisioner createProvisioner(String name, AllocatedUnicastRange unicastRange, AllocatedGroupRange groupRange, AllocatedSceneRange sceneRange) throws IllegalArgumentException
      Creates a provisioner
      Parameters:
      name - Provisioner name
      unicastRange - AllocatedUnicastRange for the provisioner
      groupRange - AllocatedGroupRange for the provisioner
      sceneRange - AllocatedSceneRange for the provisioner
      Returns:
      Provisioner
      Throws:
      IllegalArgumentException - if the name is empty

    • selectProvisioner

      public final void selectProvisioner(Provisioner provisioner)
      Selects a provisioner if there are multiple provisioners.
      Parameters:
      provisioner - Provisioner

    • addProvisioner

      public boolean addProvisioner(Provisioner provisioner) throws IllegalArgumentException
      Adds a provisioner to the network
      Parameters:
      provisioner - Provisioner
      Throws:
      IllegalArgumentException - if unicast address is invalid, in use by a node

    • getNode

      public ProvisionedMeshNode getNode(int unicastAddress)
      Returns the mesh node with the corresponding unicast address
      Parameters:
      unicastAddress - unicast address of the node

    • getNode

      public ProvisionedMeshNode getNode(String uuid)
      Returns the mesh node with the corresponding unicast address
      Parameters:
      uuid - unicast address of the node

    • loadSequenceNumbers

      protected void loadSequenceNumbers()
      Loads the sequence numbers known to the network

    • isProvisionerUuidInUse

      protected boolean isProvisionerUuidInUse(String uuid)

    • getProvisioners

      public List<Provisioner> getProvisioners()
      Returns the list of Provisioner

    • getSelectedProvisioner

      public Provisioner getSelectedProvisioner()
      Returns the selected provisioner in the network

    • getNodes

      public List<ProvisionedMeshNode> getNodes()
      Returns the list of ProvisionedMeshNode

    • getNetworkExclusions

      public Map<Integer,List<Integer>> getNetworkExclusions()
      Returns the map of network exclusions

    • getProxyFilter

      public ProxyFilter getProxyFilter()
      Returns the ProxyFilter set on the proxy

    • setProxyFilter

      public void setProxyFilter(ProxyFilter proxyFilter)
      Sets the ProxyFilter settings on the proxy

      Please note that this is not persisted within the node since the filter is reinitialized to a whitelist filter upon connecting to a proxy node. Therefore after setting a proxy filter and disconnecting users will have to manually

    • deleteNode

      public boolean deleteNode(ProvisionedMeshNode meshNode)
      Deletes a mesh node from the list of provisioned nodes

      Note that deleting a node manually will not reset the node, but only be deleted from the stored list of provisioned nodes. However you may still be able to connect to the same node, if it was not reset since the network may still exist. This would be useful to in case if a node was physically reset and needs to be removed from the mesh network/db

      Parameters:
      meshNode - node to be deleted
      Returns:
      true if deleted and false otherwise