Package com.reduxrobotics.canand

Class CanandSettingsManager<T extends CanandSettings>

java.lang.Object
com.reduxrobotics.canand.CanandSettingsManager<T>
Type Parameters:
T - the specialized settings object type that this manages
public class CanandSettingsManager<T extends CanandSettings> extends Object
Common logic for settings management for CanandDevices. This class holds a CanandSettings cache of known settings received from the CAN bus, and offers a series of helper functions that provide common logic for bulk settings operations.

  • Field Details

    • kFlag_Ephemeral

      public static final int kFlag_Ephemeral
      Bit flag specifying this setting should be set ephemeral.,
      See Also:

  • Constructor Details

    • CanandSettingsManager

      public CanandSettingsManager(CanandDevice dev, CanandSettingsManager.CanandSettingsCtor<T> ctor)
      Construct a new CanandSettingsManager.
      Parameters:
      dev - the device to be associated with this object.
      ctor - the constructor of the CanandSettings subclass.

  • Method Details

    • getSettingSubset

      public T getSettingSubset(int settingCmdIndex, int[] subset, double timeout, double missingTimeout, int missingAttempts)
      Fetches a setting subset given the setting command to request with and list of indexes that are expected to be received.
      Parameters:
      settingCmdIndex - the setting command index to send
      subset - the list of setting indexes to expect to receive
      timeout - in seconds for settings to be received
      missingTimeout - maximum number of seconds to wait for each settings retry before giving up
      missingAttempts - if >0, lists how many times to attempt fetching missing settings.
      Returns:
      CanandSettings representing what has been received of the device's configuration.

    • fetchMissingSettingsSubset

      public List<Integer> fetchMissingSettingsSubset(int[] subset, double timeout, int attempts)
      Fetches a list of settings that are missing from the known settings set.
      Parameters:
      subset - list of settings that the known settings cache is to be filled with.
      timeout - how long to wait to fetch individual settings that were not received
      attempts - how many times to attempt fetching each setting that has not been received.
      Returns:
      a list of setting indexes that are still missing, despite attempts

    • getSettings

      public T getSettings(double timeout, double missingTimeout, int missingAttempts)
      Fetches the device's current configuration in a blocking manner. This function will block for at least `timeout` seconds waiting for the device to reply, so it is best to put this in a teleop or autonomous init function, rather than the main loop.
      Parameters:
      timeout - maximum number of seconds to wait for the all settings pass before giving up
      missingTimeout - maximum number of seconds to wait for each settings retry before giving up
      missingAttempts - if >0, lists how many times to attempt fetching missing settings.
      Returns:
      CanandSettings representing what has been received of the device's configuration.

    • startFetchSettings

      public void startFetchSettings()
      Tells the device to begin transmitting its settings. Once they are all transmitted (typically after ~200-300ms), the values can be retrieved from getKnownSettings()

    • setSettings

      public T setSettings(T settings, double timeout, int attempts)
      Applies the settings from a CanandSettings object to the device, with fine grained control over failure-handling. This overload allows specifiyng the number of retries per setting as well as the confirmation timeout. Additionally, it returns a CanandSettings object of settings that were not able to be successfully applied.
      Parameters:
      settings - the CanandSettings to update the device with
      timeout - maximum time in seconds to wait for each setting to be confirmed. Set to 0 to not check (and not block).
      attempts - the maximum number of attempts to write each individual setting
      Returns:
      a CanandSettings object of unsuccessfully set settings.

    • setSettings

      public boolean setSettings(T settings, double timeout)
      Applies the settings from a CanandSettings object to the device.
      Parameters:
      settings - the CanandSettings to update the device with
      timeout - maximum time in seconds to wait for each setting to be confirmed. Set to 0 to not check (and not block).
      Returns:
      true if successful, false if a setting operation failed

    • sendReceiveSettingCommand

      public T sendReceiveSettingCommand(int cmd, double timeout, boolean clearKnown)
      Runs a setting command that may mutate all settings and trigger a response. Typically used with "reset factory default" type commands
      Parameters:
      cmd - setting index
      timeout - total timeout for all settings to be returned
      clearKnown - whether to clear the set of known settings
      Returns:
      the set of known settings.

    • getKnownSettings

      public T getKnownSettings()
      Return a CanandSettings of known settings. The object returned is a copy of this object's internal copy.
      Returns:
      known settings

    • handleSetting

      public void handleSetting(CanandMessage msg)
      Setting handler to put in CanandDevice.handleMessage(com.reduxrobotics.canand.CanandMessage). Example: 
       // boilerplate definition (in practice it won't be null)
 CanandSettingsManager settingsMgr = null;
 // from your handler:
 CanandMessage msg = new CanandMessage();
 
 // in the handler:
 switch(msg.getApiIndex()) {
    case CanandDeviceDetails.Msg.kReportSetting: {
        if (settingsMgr == null) break;
        settingsMgr.handleSetting(msg);
        break;
    } 
    default: break;
 }
      Parameters:
      msg - the CanandMessage containing the settings data to process (from handleMessage)

    • setSettingById

      public void setSettingById(int settingId, long value, int flags)
      Directly sends a CAN message to the associated CanandDevice to set a setting by index. This function does not block nor check if a report settings message is sent in response.

      Device subclasses will usually have a more user-friendly settings interface, eliminating the need to call this function directly in the vast majority of cases.

      Parameters:
      settingId - the setting id
      value - the raw numerical value. Only the lower 48 bits will be used.
      flags - optional flags to send to the device specifying how the setting will be set.

    • setSettingById

      public void setSettingById(int settingId, byte[] value, int flags)
      Directly sends a CAN message to the associated CanandDevice to set a setting by index. This function does not block nor check if a report settings message is sent in response.

      Device subclasses will usually have a more user-friendly settings interface, eliminating the need to call this function directly in the vast majority of cases.

      Parameters:
      settingId - the setting id
      value - a value byte array. Up to the first 6 bytes will be used.
      flags - optional flags to send to the device specifying how the setting will be set.

    • confirmSetSetting

      public CanandSettingsManager.SettingResult confirmSetSetting(int settingIdx, long payload, double timeout, int flags, int attempts)
      Potentially blocking operation to send a setting and wait for a report setting message to be received to confirm the operation, with retries.
      Parameters:
      settingIdx - Setting index to set and listen for
      payload - the long value to send. Only lower 48 bits are used.
      timeout - the timeout to wait before giving up in seconds. Passing in 0 will return instantly (not block)
      flags - optional flags to send to the device specifying how the setting will be set.
      attempts - number of times to attempt a retry
      Returns:
      the value received by the report setting packet if existent or CanandSettingsManager.SettingResult.TIMEOUT otherwise. If timeout = 0, return "payload" (assume success)

    • confirmSetSetting

      public CanandSettingsManager.SettingResult confirmSetSetting(int settingIdx, long payload, double timeout, int flags)
      Potentially blocking operation to send a setting and wait for a report setting message to be received to confirm the operation.
      Parameters:
      settingIdx - Setting index to set and listen for
      payload - the long value to send. Only lower 48 bits are used.
      timeout - the timeout to wait before giving up in seconds. Passing in 0 will return instantly (not block)
      flags - optional flags to send to the device specifying how the setting will be set.
      Returns:
      the value received by the report setting packet if existent or CanandSettingsManager.SettingResult.TIMEOUT otherwise. If timeout = 0, return "payload" (assume success)

    • fetchSetting

      public CanandSettingsManager.SettingResult fetchSetting(int settingIdx, double timeout)
      Fetches a setting from the device and returns the received result.
      Parameters:
      settingIdx - Setting index to fetch
      timeout - timeout to wait before giving up in seconds. Passing in 0 will return CanandSettingsManager.SettingResult.TIMEOUT.
      Returns:
      CanandSettingsManager.SettingResult representing the setting result.

    • sendSettingCommand

      public void sendSettingCommand(int settingCmdIdx)
      Sends a setting command with no arguments.
      Parameters:
      settingCmdIdx - the index of the setting command to send.