Skip to content

Docs: fix I2CSlave documentation #8506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 24, 2018
Merged

Docs: fix I2CSlave documentation #8506

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
52a0b64
fix documentation and example
paul-szczepanek-arm Oct 23, 2018
f9ae6a3
hide protected
paul-szczepanek-arm Oct 23, 2018
7fa3a44
Copy edit I2CSlave.h
Oct 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 55 additions & 47 deletions drivers/I2CSlave.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,38 +25,41 @@
namespace mbed {
/** \addtogroup drivers */

/** An I2C Slave, used for communicating with an I2C Master device
/** An I2C Slave, used for communicating with an I2C Master device.
*
* @note Synchronization level: Not protected
*
* Example:
* Example Simple I2C responder:
* @code
* // Simple I2C responder
* #include <mbed.h>
*
* I2CSlave slave(p9, p10);
* const int SLAVE_ADDRESS = 0xA0;
* const char message[] = "Slave!";
*
* int main() {
* char buf[10];
* char msg[] = "Slave!";
* I2CSlave slave(I2C_SDA, I2C_SCL);
*
* slave.address(0xA0);
* int main() {
* slave.address(SLAVE_ADDRESS);
* while (1) {
* int i = slave.receive();
* switch (i) {
* int operation = slave.receive();
* switch (operation) {
* case I2CSlave::ReadAddressed:
* slave.write(msg, strlen(msg) + 1); // Includes null char
* int status = slave.write(message, sizeof(message));
* if (status == 0) {
* printf("Written message: %s\n", message);
* } else {
* printf("Failed to write message.\n");
* }
* break;
* case I2CSlave::WriteGeneral:
* slave.read(buf, 10);
* printf("Read G: %s\n", buf);
* int byte_read = slave.read();
* printf("Read General: %c (%d)\n", byte_read, byte_read);
* break;
* case I2CSlave::WriteAddressed:
* slave.read(buf, 10);
* printf("Read A: %s\n", buf);
* int byte_read = slave.read();
* printf("Read Addressed: %c (%d)\n", byte_read, byte_read);
* break;
* }
* for(int i = 0; i < 10; i++) buf[i] = 0; // Clear buffer
* }
* }
* @endcode
Expand All @@ -74,71 +77,71 @@ class I2CSlave {

/** Create an I2C Slave interface, connected to the specified pins.
*
* @param sda I2C data line pin
* @param scl I2C clock line pin
* @param sda I2C data line pin.
* @param scl I2C clock line pin.
*/
I2CSlave(PinName sda, PinName scl);

/** Set the frequency of the I2C interface
/** Set the frequency of the I2C interface.
*
* @param hz The bus frequency in hertz
* @param hz The bus frequency in Hertz.
*/
void frequency(int hz);

/** Checks to see if this I2C Slave has been addressed.
/** Check if this I2C Slave has been addressed.
*
* @returns
* A status indicating if the device has been addressed, and how
* - NoData - the slave has not been addressed
* - ReadAddressed - the master has requested a read from this slave
* - WriteAddressed - the master is writing to this slave
* - WriteGeneral - the master is writing to all slave
* @return A status indicating if the device has been addressed and how.
* @retval NoData The slave has not been addressed.
* @retval ReadAddressed The master has requested a read from this slave.
* @retval WriteAddressed The master is writing to this slave.
* @retval WriteGeneral The master is writing to all slave.
*/
int receive(void);

/** Read from an I2C master.
/** Read specified number of bytes from an I2C master.
*
* @param data pointer to the byte array to read data in to
* @param length maximum number of bytes to read
* @param data Pointer to the buffer to read data into.
* @param length Number of bytes to read.
*
* @returns
* 0 on success,
* non-0 otherwise
* @return Result of the operation.
* @retval 0 If the number of bytes read is equal to length requested.
* @retval nonzero On error or if the number of bytes read is less than requested.
*/
int read(char *data, int length);

/** Read a single byte from an I2C master.
*
* @returns
* the byte read
* @return The byte read.
*/
int read(void);

/** Write to an I2C master.
*
* @param data pointer to the byte array to be transmitted
* @param length the number of bytes to transmite
* @param data Pointer to the buffer containing the data to be sent.
* @param length Number of bytes to send.
*
* @returns
* 0 on success,
* non-0 otherwise
* @return
* @retval 0 If written all bytes successfully.
* @retval nonzero On error or if the number of bytes written is less than requested.
*/
int write(const char *data, int length);

/** Write a single byte to an I2C master.
*
* @param data the byte to write
* @param data Value to write.
*
* @returns
* '1' if an ACK was received,
* '0' otherwise
* @return Result of the operation.
* @retval 0 If a NACK is received.
* @retval 1 If an ACK is received.
* @retval 2 On timeout.
*/
int write(int data);

/** Sets the I2C slave address.
/** Set the I2C slave address.
*
* @param address The address to set for the slave (least significant bit is ignored).
*
* @param address The address to set for the slave (ignoring the least
* signifcant bit). If set to 0, the slave will only respond to the
* @note If address is set to 0, the slave will only respond to the
* general call address.
*/
void address(int address);
Expand All @@ -147,8 +150,13 @@ class I2CSlave {
*/
void stop(void);

#if !defined(DOXYGEN_ONLY)

protected:
/* Internal i2c object identifying the resources */
i2c_t _i2c;

#endif //!defined(DOXYGEN_ONLY)
};

} // namespace mbed
Expand Down