Improvements to setMaxAngle() / setStartPosition() / setEndPosition()

[sheffieldnikki]

Sorry for all the editing - changed my mind! See next comment for new versions.

[sheffieldnikki]

Here are new versions of the set_() and get_() functions. Suggested improvements:

1. Simplified code if no argument (-1)
2. Reads back the newly set register value using get_() functions instead of duplicating that code in each set_() function
3. Uses new shared writeTwoBytes() function to write double byte i2c registers, for smaller code size and better readability
4. Added return value to setConf(), for consistency with other set_() functions
5. Fixed typo "setEndtPosition" in comment
6. Simplified getEndPosition()
7. Better documentation of what happens if no function argument
8. Better documentation with min/max values, and how to use start+end or start+range for scaled outputs

I don't think setMaxAngle() / getMaxAngle() are ideal function names since the MANG register doesn't set the "max angle" but rather than angular range or 'width' from the start position angle. I haven't renamed them though, just improved the documentation.

/*******************************************************
  In: new angular range to set 205..4095, OR none
  Out: value of angular range register
  Description: sets a value in angular range register.
  Must be greater than 18 degrees (204). Use with start:
  start=10 deg + range=90 deg gives 10..100 degrees for 
  output from getScaledAngle.
  If no value is provided, method will set from start
  position to current position of magnet.
*******************************************************/
word AMS_5600::setMaxAngle(word newMaxAngle)
{
  if (newMaxAngle == -1) newMaxAngle = getRawAngle();
  writeTwoBytes(_addr_mang, newMaxAngle);
  return getMaxAngle();
}

/*******************************************************
  Method: getMaxAngle
  In: none
  Out: value of angular range register 205..4095
  Description: gets value of angular range register.
*******************************************************/
word AMS_5600::getMaxAngle()
{
  return readTwoBytesSeparately(_addr_mang);
}

/*******************************************************
  Method: setStartPosition
  In: new start angle position 0..4095, OR none
  Out: value of start position register
  Description: sets a value in start position register.
  If no value is provided, method will set to current 
  position of magnet.
*******************************************************/
word AMS_5600::setStartPosition(word startAngle)
{
  if (startAngle == -1) startAngle = getRawAngle();
  writeTwoBytes(_addr_zpos, startAngle);
  return getStartPosition();
}

/*******************************************************
  Method: getStartPosition
  In: none
  Out: value of start position register 0..4095
  Description: gets value of start position register.
*******************************************************/
word AMS_5600::getStartPosition()
{
  return readTwoBytesSeparately(_addr_zpos);
}

/*******************************************************
  Method: setEndPosition
  In: new end angle position 0..4095, OR none
  Out: value of end position register
  Description: sets a value in end position register.
  Use with start: start=10 deg + end=180 deg gives 
  10..180 degrees for output from getScaledAngle.
  If no value is provided, method will set to current 
  position of magnet.
*******************************************************/
word AMS_5600::setEndPosition(word endAngle)
{
  if (endAngle == -1) endAngle = getRawAngle();
  writeTwoBytes(_addr_mpos, endAngle);
  return getEndPosition();
}

/*******************************************************
  Method: getEndPosition
  In: none
  Out: value of end position register 0..4095
  Description: gets value of end position register.
*******************************************************/
word AMS_5600::getEndPosition()
{
  return readTwoBytesSeparately(_addr_mpos);
}

/*******************************************************
  Method: getRawAngle
  In: none
  Out: value of raw angle register 0..4095
  Description: gets raw value of magnet position.
  start, end/max angle settings do not apply.
*******************************************************/
word AMS_5600::getRawAngle()
{
  return readTwoBytesTogether(_addr_raw_angle);
}

/*******************************************************
  Method: getScaledAngle
  In: none
  Out: value of scaled angle register 0..4095
  Description: gets scaled value of magnet position.
  start and end/max angle settings are used to convert
  a reduced range (eg, 10..100 degrees) to full 0..4095 
  values for greater resolution.
*******************************************************/
word AMS_5600::getScaledAngle()
{
  return readTwoBytesTogether(_addr_angle);
}

/*******************************************************
  Method: setConf
  In: value of CONF register, see datasheet
  Out: value of CONF register
  Description: sets value of CONF register.
*******************************************************/
word AMS_5600::setConf(word _conf)
{
  writeTwoBytes(_addr_conf, _conf);
  return getConf();
}

and a new function writeTwoBytes():

/*******************************************************
  Method: writeTwoBytes
  In: address and data to write
  Out: none
  Description: writes two bytes to an i2c register.
*******************************************************/
void AMS_5600::writeTwoBytes(int adr_in, word dat_in)
{
  writeOneByte(adr_in,   highByte(dat_in));
  delay(2);
  writeOneByte(adr_in+1, lowByte(dat_in));
  delay(2);
}

[sheffieldnikki]

I haven't tested it, but this is a much faster way to write 2 bytes, without setting the register address separately for the high and low bytes, and without delay() calls:

void AMS_5600::writeTwoBytes(int adr_in, word dat_in)
{
  Wire.beginTransmission(_ams5600_Address);
  Wire.write(adr_in);
  Wire.write(highByte(dat_in));
  Wire.write(lowByte(dat_in));  // automatic adr_in+1
  Wire.endTransmission();
}

[dwarning]

Sorry, if it is off topic: Arduino 1.8.19 using esp8266 complains that e.g. startAngle == -1 can never happen because word seems unsigned 16bit. In case you want change the functions.