dev: add documentation on simulated i2c devices

dev/source/docs/adding_simulated_devices.rst

@@ -6,6 +6,15 @@ Adding Simulated Peripherals to sim_vehicle
 
 Several devices can be simulated within SITL. These include Gimbals, Beacons, Rangefinders, VICON, RPM sensors,etc.
 
+Starting with CAN based simulated peripherals
+=============================================
+
+When SITL is started, it has a standard set of peripherals (ie GPS, ESCs, Servos for flying surfaces, Power Monitors, etc.) simulated also. However, these can be simulated as DroneCAN devices instead to allow monitoring of CAN behavior, allow testing of new AP_Periph devices in the simulation, etc. To start SITL using these peripherals, instead of the normally connected ones:
+
+::
+
+   sim_vehicle.py -v <vehicle> --console --map --can-peripherals
+
 Simulating On-Board OSD
 =======================
 
@@ -17,6 +26,14 @@ When starting SITL, you can have it display a simulation of the integated OSD, i
 
 .. note:: the OSD emulation displays OSD panel items and locations, but it does not allow multiple screens, nor units other than metric
 
+Simulating I2C devices
+======================
+
+.. toctree::
+    :maxdepth: 1
+
+    sitl-i2c-devices
+
 
 Adding a Virtual Gimbal
 =======================

dev/source/docs/sitl-i2c-devices.rst

@@ -0,0 +1,45 @@
+.. _sitl-i2c-devices:
+
+================
+SITL I2C Devices
+================
+
+The SITL (software in the loop) simulates many different i2c devices, including:
+
+- MaxSonar i2c-connected sonar
+- various SMBus battery monitors
+- LED devices
+- temperature sensors
+- airspeed sensors
+- IMU drivers
+
+Overview
+========
+
+``SITL/SIM_I2C.cpp`` contains the instantitions and initialisation of the buses and drivers.  It also contains the hook used by the SITL HAL to make simulated i2c bus transactions with the device, ``I2C::ioctl``
+
+``SITL/SIM/I2CDevice.h`` declares the I2CDevice class from which all simulated I2C drivers inherit from.  The general structure of an I2CDevice is:
+
+ - an init() method
+ - an ``update`` method called periodically to simulate whatever the device accomplishes on its own internal clock
+ - a ``rdwr`` call which is called when ArduPilot attempts an i2c transaction
+
+i2c devices vary in the structure of the on-wire protocol.  Some examples of protocol shapes include:
+
+- simply stream bytes onto the i2c bus; when a read is attempted from one of these devices a response is received with bytes filled in, regardless of what transfer is made to the device.  SIM_Airspeed_DLVR is an example of an implementation of this sort of device, never allowing i2c writes to the device and always returning 4 bytes of data.
+
+- respond to a simple i2c "take reading command" by making available a reading on a subsequent i2c read transaction.  The SIM_MaxSonarI2CXL is an example of this sort of device, responding to a command of 0x51 by taking a measurement and allowing a subsequent read of 2 bytes to return that measurement.
+
+- a register-based interface where the ArduPilot driver writes to registers at specific offsets to configure the device and reads data back via the same interface.  i2c transactions are usually a pair of couple transactions, one to specify the registers to read and the other for the simulated device to return the data.  The simulated IS31FL3195 LED driver is an example of this, presenting a number of control registers used for setting the LED patterns and device behaviour.  These i2c devices often have a "WHOAMI" register to determine the device type.  SMBus devices also often speak this protocol, but using 16-bit registers rather than the usual 8-bit.
+
+Choosing a Device Style
+=======================
+
+When implementing a new simulator, care must be taken to choose the correct "style" of simulator to implement.  Several base classes can be inheritted from to prevent warrantless duplication.  As always, find a good example of something similar to the device you wish to simulate and "do what that thing does".  Working out what the protocol is requires study of the datasheet for the device.
+
+For devices which are strictly register-based, the ``I2CRegisters_8Bit`` (or ``I2CRegisters_16Bit``) base class should be inheritted from.  This allows your new simulator to describe the registers present on the device, and simply fill the register values in based on how ArduPilot manipulates other registers.  It is also possible to create simulates devices with both 8 and 16 bit registers - see ``I2CRegisters_ConfigurableLength``
+
+For devices which are polled to start some sort of measurement and subsequently make available a 16-bit quantity for reading ``I2CCommandResponseDevice`` may be used to write a simple driver.
+
+For devices which simply return fixed-length readings when an i2c "read" is made - and for any other protocol which doesn't yet have an abstraction - your simulation will need to implement the virtual method ``rdwr(I2C::i2c_rdwr_ioctl_data *&data)`` inheritted from SITL::I2CDevice.
+

dev/source/docs/using-sitl-for-ardupilot-testing.rst

@@ -154,15 +154,10 @@ the default working directory will be the directory in which sim_vehicle.py was
 
     sim_vehicle.py -v ArduPlane --console --map --add-param-file=<path to file> -w
 
-Starting with CAN based simulated peripherals
----------------------------------------------
-
-When SITL is started, it has a standard set of peripherals (ie GPS, ESCs, Servos for flying surfaces, Power Monitors, etc.) simulated also. However, these can be simulated as DroneCAN devices instead to allow monitoring of CAN behavior, allow testing of new AP_Periph devices in the simulation, etc. To start SITL using these peripherals, instead of the normally connected ones:
-
-::
-
-   sim_vehicle.py -v <vehicle> --console --map --can-peripherals
+Adding Simulated Peripherals into the Simulation
+------------------------------------------------
 
+See :ref:`adding_simulated_devices`
 
 Using real serial devices
 -------------------------
@@ -212,6 +207,8 @@ is equivalent to COM16:
 
     sim_vehicle.py -A "--serial1=uart:/dev/ttyS15" --console --map
 
+Using real I2C de
+
 .. _using-sitl-for-ardupilot-testing_sitl_without_mavproxy_tcp:
 
 Replaying serial data from Saleae Logic data captures