Better variable naming.

docs/protocol.rst

@@ -9,7 +9,7 @@ Packets
 
 Communication over a shared serial connection is accomplished by using
 packets. The packet structure is straightforward, every message is prefixed
-by a virtual port number and the length of the message.
+by a virtual serial port number and the length of the message.
 
 .. list-table:: Packet structure.
    :header-rows: 1
@@ -19,18 +19,17 @@ by a virtual port number and the length of the message.
      - description
    * - 0
      - 1
-     - virtual port
+     - virtual serial port
    * - 1
      - 1
      - size
    * - 2
      - size
      - data
 
-The first virtual device has port number ``0``, the second ``1``, etc.
-Virtual port number ``255`` is reserved for control messages. The maximum
-number of virtual devices is 254 and the length of the message is limited to
-255 bytes.
+The first virtual device has port number ``0``, the second ``1``, etc. Port
+number ``255`` is reserved for control messages. The maximum number of virtual
+devices is 254 and the length of the message is limited to 255 bytes.
 
 
 Control messages
@@ -54,8 +53,8 @@ up.
      - ``\x01\x00\x00`` (example)
      - Version (major, minor, patch).
    * - 2
-     - Number of virtual ports.
-     - Get the number of virtual ports.
+     - Number of virtual serial ports.
+     - Get the number of virtual serial ports.
    * - 3
      - ``0x00``
      - Enable multiplexer.
@@ -72,9 +71,10 @@ A typical initialisation procedure looks as follows.
 2. The device responds with the protocol identifier.
 3. The host asks for the protocol version (``0xff, 0x01, 0x01``).
 4. The device responds with the protocol version.
-5. The host requests the number of virtual ports (``0xff, 0x01, 0x02``).
-6. The device sends the number of virtual ports (e.g., ``0xff, 0x01, 0x02``).
-7. The host sets up pseudo terminals that connect to the virtual ports.
+5. The host requests the number of virtual serial ports (``0xff, 0x01, 0x02``).
+6. The device sends the number of virtual serial ports (e.g., ``0xff, 0x01,
+   0x02``).
+7. The host sets up pseudo terminals that connect to the virtual serial ports.
 8. The host send the enable command (``0xff, 0x01, 0x03``).
 9. The device responds with an acknowledgement (``0xff, 0x01, 0x00``).
 

src/serialMux.tcc

@@ -35,7 +35,7 @@ class SerialMux {
   private:
     Buffer<bits>* _buffer = NULL;
     bool _enabled = false;
-    uint8_t _id = 0;
+    uint8_t _ports = 0;
     Stream* _serial = NULL;
 
     void _control(void);
@@ -68,98 +68,98 @@ SerialMux<bits>::~SerialMux(void) {
 /*!
  * Add a virtual serial device.
  *
- * \return New virtual serial device ID.
+ * \return New virtual serial port.
  */
 template <uint8_t bits>
 uint8_t SerialMux<bits>::add(void) {
   _buffer = (Buffer<bits>*)realloc(
-    (void*)_buffer, ++_id * sizeof(Buffer<bits>));
-  _buffer[_id - 1] = Buffer<bits>();
-  return _id - 1;
+    (void*)_buffer, ++_ports * sizeof(Buffer<bits>));
+  _buffer[_ports - 1] = Buffer<bits>();
+  return _ports - 1;
 }
 
 
 /*!
  * Get the number of bytes available for reading.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  *
  * \return Number of bytes.
  */
 template <uint8_t bits>
-size_t SerialMux<bits>::available(uint8_t id) {
+size_t SerialMux<bits>::available(uint8_t port) {
   _update();
-  return _buffer[id].available();
+  return _buffer[port].available();
 }
 
 /*!
  * Read `size` bytes of data.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  * \param data Buffer to receive `size` bytes of data.
  * \param size Number of bytes to read.
  *
  * \return Number of bytes read.
  */
 template <uint8_t bits>
-size_t SerialMux<bits>::read(uint8_t id, uint8_t* data, uint8_t size) {
+size_t SerialMux<bits>::read(uint8_t port, uint8_t* data, uint8_t size) {
   _update();
-  return _buffer[id].read(data, size);
+  return _buffer[port].read(data, size);
 }
 
 /*!
  * Read one byte of data.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  *
  * \return The first byte of incoming data or `-1` if no data is available.
  */
 template <uint8_t bits>
-int SerialMux<bits>::read(uint8_t id) {
+int SerialMux<bits>::read(uint8_t port) {
   _update();
-  return _buffer[id].read();
+  return _buffer[port].read();
 }
 
 /*!
  * Write `size` bytes of data.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  * \param data Buffer containing `size` bytes of data.
  * \param size Number of bytes to write.
  *
  * \return Number of bytes written.
  */
 template <uint8_t bits>
-size_t SerialMux<bits>::write(uint8_t id, uint8_t* data, uint8_t size) {
+size_t SerialMux<bits>::write(uint8_t port, uint8_t* data, uint8_t size) {
   _update();
-  return _write(id, data, size);
+  return _write(port, data, size);
 }
 
 /*!
  * Write one byte of data.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  * \param data Data.
  *
  * \return Number of bytes written.
  */
 template <uint8_t bits>
-size_t SerialMux<bits>::write(uint8_t id, uint8_t data) {
+size_t SerialMux<bits>::write(uint8_t port, uint8_t data) {
   _update();
-  return _write(id, &data, 1);
+  return _write(port, &data, 1);
 }
 
 /*!
  * Return the next byte of incoming data without removing it from the buffer.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  *
  * \return The first byte of incoming data or `-1` if no data is available.
  */
 template <uint8_t bits>
-int SerialMux<bits>::peek(uint8_t id) {
+int SerialMux<bits>::peek(uint8_t port) {
   _update();
-  return _buffer[id].peek();
+  return _buffer[port].peek();
 }
 
 
@@ -176,7 +176,7 @@ void SerialMux<bits>::_control(void) {
       write(_CONTROL_PORT, (uint8_t*)_VERSION, sizeof(_VERSION) - 1);
       return;
     case CMD_GET_PORTS:
-      write(_CONTROL_PORT, _id);
+      write(_CONTROL_PORT, _ports);
       return;
     case CMD_ENABLE:
       _enabled = true;
@@ -191,19 +191,19 @@ void SerialMux<bits>::_control(void) {
 }
 
 /*
- * Distribute incoming data over virtual serial devices.
+ * Send incoming data to virtual serial ports.
  */
 template <uint8_t bits>
 void SerialMux<bits>::_update(void) {
   if (_serial->available()) {
-    uint8_t id = _read();
+    uint8_t port = _read();
     uint8_t size = _read();
-    if (id == _CONTROL_PORT) {
+    if (port == _CONTROL_PORT) {
       _control();
       return;
     }
     for (uint8_t i = 0; i < size; i++) {
-      _buffer[id].write(_read());
+      _buffer[port].write(_read());
     }
   }
 }
@@ -223,16 +223,16 @@ uint8_t SerialMux<bits>::_read(void) {
 /*
  * Write `size` bytes of data.
  *
- * \param id Virtual device ID.
+ * \param port Virtual serial port.
  * \param data Buffer containing `size` bytes of data.
  * \param size Number of bytes to write.
  *
  * \return Number of bytes written.
  */
 template <uint8_t bits>
-size_t SerialMux<bits>::_write(uint8_t id, uint8_t* data, uint8_t size) {
-  if (_enabled || id == _CONTROL_PORT) {
-    _serial->write(id);
+size_t SerialMux<bits>::_write(uint8_t port, uint8_t* data, uint8_t size) {
+  if (_enabled || port == _CONTROL_PORT) {
+    _serial->write(port);
     _serial->write(size);
     return _serial->write(data, size);
   }

src/vSerial.tcc

@@ -23,7 +23,7 @@ class VSerial : public Stream {
 
   private:
     SerialMux<bits>* _mux = NULL;
-    uint8_t _id = 0;
+    uint8_t _port = 0;
 };
 
 
@@ -35,7 +35,7 @@ class VSerial : public Stream {
 template <uint8_t bits>
 VSerial<bits>::VSerial(SerialMux<bits>& mux) {
   _mux = &mux;
-  _id = _mux->add();
+  _port = _mux->add();
 }
 
 
@@ -46,7 +46,7 @@ VSerial<bits>::VSerial(SerialMux<bits>& mux) {
  */
 template <uint8_t bits>
 int VSerial<bits>::available(void) {
-  return _mux->available(_id);
+  return _mux->available(_port);
 }
 
 /*!
@@ -56,7 +56,7 @@ int VSerial<bits>::available(void) {
  */
 template <uint8_t bits>
 int VSerial<bits>::read(void) {
-  return _mux->read(_id);
+  return _mux->read(_port);
 }
 
 /*!
@@ -69,7 +69,7 @@ int VSerial<bits>::read(void) {
  */
 template <uint8_t bits>
 size_t VSerial<bits>::readBytes(uint8_t* data, size_t size) {
-  return _mux->read(_id, data, size);
+  return _mux->read(_port, data, size);
 }
 
 /*!
@@ -82,7 +82,7 @@ size_t VSerial<bits>::readBytes(uint8_t* data, size_t size) {
  */
 template <uint8_t bits>
 size_t VSerial<bits>::write(uint8_t* data, size_t size) {
-  return _mux->write(_id, data, size);
+  return _mux->write(_port, data, size);
 }
 
 /*!
@@ -94,7 +94,7 @@ size_t VSerial<bits>::write(uint8_t* data, size_t size) {
  */
 template <uint8_t bits>
 size_t VSerial<bits>::write(uint8_t data) {
-  return _mux->write(_id, data);
+  return _mux->write(_port, data);
 }
 
 /*!
@@ -107,7 +107,7 @@ size_t VSerial<bits>::write(uint8_t data) {
 template <uint8_t bits>
 template <class T>
 size_t VSerial<bits>::write(T data) {
-  return _mux->write(_id, (uint8_t*)&data, sizeof(T));
+  return _mux->write(_port, (uint8_t*)&data, sizeof(T));
 }
 
 /*!
@@ -117,7 +117,7 @@ size_t VSerial<bits>::write(T data) {
  */
 template <uint8_t bits>
 int VSerial<bits>::peek(void) {
-  return _mux->peek(_id);
+  return _mux->peek(_port);
 }
 
 /*!
@@ -129,7 +129,7 @@ int VSerial<bits>::peek(void) {
  */
 template <uint8_t bits>
 size_t VSerial<bits>::print(char const data[]) {
-  return _mux->write(_id, (uint8_t*)data, strlen(data));
+  return _mux->write(_port, (uint8_t*)data, strlen(data));
 }
 
 /*!
@@ -141,5 +141,5 @@ size_t VSerial<bits>::print(char const data[]) {
  */
 template <uint8_t bits>
 size_t VSerial<bits>::print(String& data) {
-  return _mux->write(_id, (uint8_t*)data.c_str(), data.length());
+  return _mux->write(_port, (uint8_t*)data.c_str(), data.length());
 }