Update with the latest information on peripheral numbering (pure int numbering is implausible) and pin specification in peripherals (use pin-named kwargs, not pins=(tuple_of_unknown_order)).

Hardware-API.md

@@ -54,7 +54,7 @@ You make objects corresponding to physical entities in the MCU (eg Pin, UART, Ti
 
 Conventions are:
 
-- Selection of a peripheral/entity is done by an id.  A port must allow to specify ids by a sequential integer starting at 0 and going to MAX (MAX is a constant defined in the periph class).  Ports can optionally allow to specify periphs by a string (this allows to write portable code across boards that provide similar periphs, specify by MCU name, etc). There can be also "virtual" peripherals, e.g. bitbanging I2C port, software timer, etc. These are recommended to have negative ids, with -1 being a default choice. If there're multiple types of the same virtual peripheral (e.g. OS software timers with different properties), further negative values can be given, and symbolic constants are recommended to be provided for them. But another implementation strategy for this case is to define separate classes for such cases, instead of overloading default Timer class - e.g. OSSlowTimer, OSFastTimer.
+- Selection of a peripheral/entity is done by an id. Whenever possible, a port should allow an ID to be an integer, but in various cases this will not be possible. Besides this recommendation, a format of an id is arbitrary (common cases: integer, strings, tuple of string/integers). There can be "virtual" peripherals, e.g. bitbanging I2C port, software timer, etc. These are recommended to have negative ids, with -1 being a default choice. If there're multiple types of the same virtual peripheral (e.g. OS software timers with different properties), further negative values can be given, and symbolic constants are recommended to be provided for them. (But another implementation strategy for this case is to define separate classes for such cases, instead of overloading default Timer class - e.g. OSSlowTimer, OSFastTimer. This is informal comment.)
 
 - All periphs provide a constructor, `.init()` and `.deinit()` methods. The `Pin` and the `IRQ` classes are the exception here, `Pin` doesn't provide `.deinit()` because a single pin cannot be completely de-initalized, and also because of the dynamic nature of pins which can be used as GPIO and also by other peripherals.
 
@@ -62,7 +62,7 @@ Conventions are:
 
 - If a peripheral is in the non-initialized state, any operation on it except for `.init()` SHOULD raise `OSError` with `EBUSY` code.
 
-- When connecting a periph to some pins, one uses the `pins=` keyword in the constructor/init function.  This is a tuple/list of pins, where each pin can be an integer, string or `Pin` instance.
+- When connecting a periph to some pins, ~~one uses the `pins=` keyword in the constructor/init function.  This is a tuple/list of pins, where each pin can be an integer, string or `Pin` instance.~~ keyword arguments with names of the pins should be used, e.g. `tx=`, `miso=`, etc.
 
 In the method specs below, *NOHEAP* means the function cannot allocate on the heap.  For some ports this may be difficult if the function needs to return an integer value that does not fit in a small integer.  Don't know what to do about this.