Merge pull request #5 from apdlv72/i2s_documentation

I2s documentation

Author: robertoostenveld

README.md

@@ -8,6 +8,47 @@ Wherever there is activity on the web interface (configuration, monitoring), the
 
 See http://robertoostenveld.nl/art-net-to-dmx512-with-esp8266/ for more details and photos, and https://robertoostenveld.nl/timing-and-jitter-in-dmx512-signals/ for a detailled look at the timing of the DMX signals.
 
+# Operating modes
+
+## UART
+
+DMX is a serial protocol and - except for different voltage levels - very similar to RS232. Therefore it is obvious to use the built-in UART (Universal Asynchronous Receiver/Transmitter)
+of the micro controller to send the DMX frames. This is the original way this sketch used to work and expects the max485 level shifter to be connected to the pin that corresponds to Serial1.
+On a Wemos D1 this is pin D4 aka TX1. In order to use UART mode, comment in the ENABLE_UART definition.
+
+## I2S
+
+However, the built-in UART provides only very limited control over e.g. number of stop bits, breaks etc. That may become a problem when you want to control devices with kind of "sloppy" firmware. When trying to control two cheap, china made moving heads, I found that they somehow reacted to the signal but showed lots of jitter and random moves, random color changes and so on.
+When connected to a commercial, manual DMX512 control panel, they worked flawlessly. An analysis with an oscilloscope showed a significant difference between the signal and the offical DMX
+standard, most obviously in the number of stop bits. The DMX standard defines 2 stop bits whereas the commercial panel sent approx. 11 bits. 
+It seems like the manufacturers of such panels are aware of the fact that there are devices which apparently need more time between two DMX channel values to process the data received.
+
+Because the buil-in UART does not allow to send more than 2 stop bits, the I2S mode (https://en.wikipedia.org/wiki/I%C2%B2S) has been implemented that supports very fine-grained control over
+the timing of every single bit. Unfortunately, the I2S data output pin is hardwired to GPIO3 (=RX0) on an ESP8266 which means that the max485 level shifter needs to be attached to this pin.
+Using a double throw switch allows to switch between those two pins as depicted in the wiring schematic below.
+
+*Warning*: When uploading your this sketch to your ESP8266, make sure to disconnect any fixtures from the XLR connector because this means sending data to RX0 and will cause your
+fixtures to do random things. This might not be a big problem with simple lamps but might cause damage when using motion devices.
+
+You can just as well use two max485 circuits and wire one to TX1/D4 and the second one to RX0 and comment in both modes (ENABLE_UART and ENABLE_I2S).
+
+Because of the number of extra stop bits, I2S mode will cause the throughput to drop from 40 frames/second to approx. 30 f/s which still should be acceptable under normal circumstances.
+
+For I2S mode, there is another conditional define (I2S_SUPER_SAFE) which not only adds extra stop bits but also extends the MBB (mark before break) and SFB (space before break)
+to the values observed with the oscilloscope. Try this if you encounter problems with a fixture although you are already using I2S mode.
+
+
+## Standalone mode
+
+Normally you would configure your Art-Net device to connect to your local WiFi after you uploaded this sketch (_and_ the static content! - see notes below).
+To do so, you will connect to the AP (access point) network the ESP8266 creates after booting for the first time.
+But there might be circumstances where you do not have access to a local WiFi network, for instance an outdoor garten pary.
+This is what the standalone mode is for. In standalone mode the sketch will not wait until a local WiFi connection was established but will start to listen for Art-Net packets
+right away on the AP network. You can then connect to this network, ignore/minimize the WiFi setup dialog and send your Art-Net packets to the corresponding network interface.
+
+Consider setting also a password in standalone mode, otherwise someone else might configure your device to connect to a random Wifi.
+
+
 # Components
 
   - Wemos D1 mini
@@ -18,6 +59,11 @@ See http://robertoostenveld.nl/art-net-to-dmx512-with-esp8266/ for more details
   - 3 or 5 pin female XLR connector
   - panel mount 2.1 x 5.5 mm DC barrel jack
   - 82 x 58 x 34 mm ABS enclosure box
+  
+  Optional for I2S mode:
+  
+  - an SPDT (single pole double throw) switch OR
+  - an extra MAX485 module and XLR connector
 
 # Wiring scheme
 

esp8266_artnet_dmx512.ino

@@ -32,8 +32,8 @@
 
 // Uncomment to send DMX data using the microcontroller's builtin UART.
 // This is the original way this sketch used to work and expects the max485 level
-// shifter to be connected to the pin that corresondents to Serial1.
-// On a Wemos D1 this is pin D4 aka RX1.
+// shifter to be connected to the pin that corresponds to Serial1.
+// On a Wemos D1 this is pin D4 aka TX1.
 #define ENABLE_UART
 
 // Uncomment to send DMX data via I2S instead of UART.

rgb_led.cpp

@@ -7,91 +7,51 @@ void ledInit() {
 }
 
 #ifdef COMMON_ANODE
+  #define LED_ON  LOW
+  #define LED_OFF HIGH
+#else 
+  #define LED_ON  HIGH
+  #define LED_OFF LOW
+#endif
 
 void ledRed() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, HIGH);
-}
-
-void ledGreen() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, HIGH);
-}
-
-void ledBlue() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, LOW);
-}
-
-void ledYellow() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, HIGH);
-}
-
-void ledMagenta() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, LOW);
-}
-
-void ledCyan() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, LOW);
-}
-
-void ledBlack() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, HIGH);
-}
-
-#else
-
-void ledRed() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, LOW);
+  digitalWrite(LED_R, LED_ON);
+  digitalWrite(LED_G, LED_OFF);
+  digitalWrite(LED_B, LED_OFF);
 }
 
 void ledGreen() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, LOW);
+  digitalWrite(LED_R, LED_OFF);
+  digitalWrite(LED_G, LED_ON);
+  digitalWrite(LED_B, LED_OFF);
 }
 
 void ledBlue() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, HIGH);
+  digitalWrite(LED_R, LED_OFF);
+  digitalWrite(LED_G, LED_OFF);
+  digitalWrite(LED_B, LED_ON);
 }
 
 void ledYellow() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, LOW);
+  digitalWrite(LED_R, LED_ON);
+  digitalWrite(LED_G, LED_ON);
+  digitalWrite(LED_B, LED_OFF);
 }
 
 void ledMagenta() {
-  digitalWrite(LED_R, HIGH);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, HIGH);
+  digitalWrite(LED_R, LED_ON);
+  digitalWrite(LED_G, LED_OFF);
+  digitalWrite(LED_B, LED_ON);
 }
 
 void ledCyan() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, HIGH);
-  digitalWrite(LED_B, HIGH);
+  digitalWrite(LED_R, LED_OFF);
+  digitalWrite(LED_G, LED_ON);
+  digitalWrite(LED_B, LED_ON);
 }
 
 void ledBlack() {
-  digitalWrite(LED_R, LOW);
-  digitalWrite(LED_G, LOW);
-  digitalWrite(LED_B, LOW);
+  digitalWrite(LED_R, LED_OFF);
+  digitalWrite(LED_G, LED_OFF);
+  digitalWrite(LED_B, LED_OFF);
 }
-
-#endif