Serial Wombat Arduino Library
SerialWombatTM1637.h
Go to the documentation of this file.
1 #pragma once
2 /*
3 Copyright 2021-2023 Broadwell Consulting Inc.
4 
5 "Serial Wombat" is a registered trademark of Broadwell Consulting Inc. in
6 the United States. See SerialWombat.com for usage guidance.
7 
8 Permission is hereby granted, free of charge, to any person obtaining a
9  * copy of this software and associated documentation files (the "Software"),
10  * to deal in the Software without restriction, including without limitation
11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
12  * and/or sell copies of the Software, and to permit persons to whom the
13  * Software is furnished to do so, subject to the following conditions:
14 
15 The above copyright notice and this permission notice shall be included in
16  * all copies or substantial portions of the Software.
17 
18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24  * OTHER DEALINGS IN THE SOFTWARE.
25 */
26 
27 #include <stdint.h>
28 #include "SerialWombat.h"
29 
36 };
37 
74 class SerialWombatTM1637:public Print, public SerialWombatPin
75 {
76 public:
81  SerialWombatTM1637(SerialWombatChip& serialWombat): SerialWombatPin(serialWombat)
82  {
83  }
84 
96  int16_t begin(uint8_t clkPin, uint8_t dioPin, uint8_t digits, SWTM1637Mode mode, uint8_t dataSourcePin, uint8_t brightness0to7)
97  {
98  _pin = clkPin;
99  uint8_t tx_200[8] = {
100  200, // Pin Set command
101  clkPin,
102  11, // TM1637
103  dioPin,
104  digits,
105  (uint8_t)mode,
106  dataSourcePin,
107  brightness0to7,
108  };
109  int16_t retval = _sw.sendPacket(tx_200);
110  return retval;
111  }
112 
113 
114  /*
115  \brief Used to reorder the digits of the display to match display hardware.
116 
117  TM1637 displays do not have a standardized wiring of LED module to the TM1637 driver pins.
118  This can cause numbers to appear in the wrong order.
119  This can be fixed by displaying the string "012345" on the display. If it appears out of
120  order, then issue this command with the parameters matching what is displayed on the screen.
121 
122  For instance, if a Six digit display showed 210543 when commanded to show "012345", calling
123  \code
124  orderDigits(2,1,0,5,4,3);
125  \endcode
126  after begin() would cause the driver to reorder the output to make the display appear in the desired order.
127 
128  \return Returns a negative error code if errors occur during configuration
129  */
130  int16_t writeDigitOrder(uint8_t first, uint8_t second, uint8_t third, uint8_t fourth, uint8_t fifth, uint8_t sixth )
131  {
132  uint8_t tx_201[8] = {
133  201, // Pin Set command
134  _pin,
135  11, // TM1637
136  first,
137  second,
138  third,
139  fourth,
140  fifth,
141  };
142  int retval = _sw.sendPacket(tx_201);
143  if (retval < 0)
144  {
145  return retval;
146  }
147  uint8_t tx_202[8] = {
148  202, // Pin Set command
149  _pin,
150  11, // TM1637
151  sixth,
152  0x55,
153  0x55,
154  0x55,
155  0x55,
156  };
157  return _sw.sendPacket(tx_202);
158  }
159 
160  /*
161  \brief Used to send data to the data array of the driver.
162 
163  \param data A 6 byte array that is sent to the display driver
164  \return Returns a negative error code if errors occur during configuration
165 
166  The meaning of this data varies based on mode. See examples.
167  */
168  int16_t writeArray(uint8_t data[6])
169  {
170  uint8_t tx_204[8] = {
171  204, // Pin Set command
172  _pin,
173  11, // TM1637
174  data[0],
175  data[1],
176  data[2],
177  data[3],
178  data[4],
179  };
180  int retval = _sw.sendPacket(tx_204);
181  if (retval < 0)
182  {
183  return retval;
184  }
185  uint8_t tx_205[8] = {
186  205, // Pin Set command
187  _pin,
188  11, // TM1637
189  data[5],
190  0x55,
191  0x55,
192  0x55,
193  0x55,
194  };
195  return _sw.sendPacket(tx_205);
196  }
197 
198  /*
199  \brief Set a bitmap of the MSB of each digit to control decimal points
200 
201  Note that TM1637 decimal point implementation varies greatly depending on the
202  display manufacturer. Setting bits may or may not cause decimal points to display,
203  the clock colon to display, or other undefined behavior. Unexpected behavior is likely
204  the result of display pcb implementation, not an issue with this library or the Serial Wombat
205  firmware.
206  \param decimalBitmapLSBleftDigit A bitmap indicating if the decimal for each digit should be lit. LSB is first digit Valid values are 0 - 0x3F
207  \return Returns a negative error code if errors occur during configuration
208 
209  */
210  int16_t writeDecimalBitmap(uint8_t decimalBitmapLSBleftDigit)
211  {
212  uint8_t tx_206[8] = {
213  206, // Pin Set command
214  _pin,
215  11, // TM1637
216  decimalBitmapLSBleftDigit,
217  0x55,
218  0x55,
219  0x55,
220  0x55,
221  };
222  return _sw.sendPacket(tx_206);
223  }
224 
225  /*
226  \brief Changes the brightness of the display
227 
228  \param Brightness - a value from 0 (dimmest) to 7 (brightest) based on the TM1637 hardware. This scale is not linear.
229  \return Returns a negative error code if errors occur during configuration
230  */
231  int16_t writeBrightness(uint8_t brightness0to7)
232  {
233  uint8_t tx_203[8] = {
234  203, // Pin Set command
235  _pin,
236  11, // TM1637
237  brightness0to7,
238  0x55,
239  0x55,
240  0x55,
241  0x55,
242  };
243  return _sw.sendPacket(tx_203);
244  }
245 
246  /*
247  \brief Loads an animation to the Serial Wombat user buffer area and initializes the animation
248 
249  The pin should have previously been initialized with the begin() command an animation mode prior to
250  this call.
251 
252  \param bufferIndex The index into the User Buffer where the data for the animation should be stored
253  \param delay How long the animation display driver should wait between loading new data
254  \param Number of Frames to be displayed before returning to the first frame. This should be the number of lines in data
255  \param data A 2 dimensional array of width 6 and arbitrary length.
256  \return Returns a negative error code if errors occur during configuration
257  */
258  int16_t writeAnimation(uint16_t bufferIndex, uint16_t delay, uint8_t numberOfFrames, uint8_t data[][6])
259  {
260  int result = _sw.writeUserBuffer(bufferIndex, (uint8_t*)data, numberOfFrames * 6);
261 
262  if (result < 0)
263  {
264  return result;
265  }
266  uint8_t settings[] = { SW_LE16(bufferIndex), SW_LE16(delay), numberOfFrames, 0 };
267  return writeArray(settings);
268 
269  }
270 
271  /*
272  \brief Whether or not to suppress leading zeros in decimal mode
273 
274  \return Returns a negative error code if errors occur during configuration
275  \param supress true: suppress leading zeros false: Do not suppress leading zeros
276  */
277  int16_t suppressLeadingZeros(bool suppress)
278  {
279  uint8_t tx_203[8] = {
280  203, // Pin Set command
281  _pin,
282  11, // TM1637
283  0x55, // Don't change brightness
284  suppress?(uint8_t)1:(uint8_t)0,
285  0x55,
286  0x55,
287  0x55,
288  };
289  return _sw.sendPacket(tx_203);
290  }
291 
292  /*
293  \brief Set a bitmap of the digits that should blink at 2Hz with 7/8 duty cycle
294 
295  This function is useful for creating user interfaces where the user increments or decrements
296  one digit of a number at a time. The blinking digit indicates the digit that will change.
297 
298  \param blinkBitmap A bitmap indicating if the decimal for each digit should be lit. LSB is first digit Valid values are 0 - 0x3F. 1 = blink
299  \return Returns a negative error code if errors occur during configuration
300 
301  */
302  int16_t writeBlinkBitmap(uint8_t blinkBitmapLSBleftDigit)
303  {
304  uint8_t tx_207[8] = {
305  207, // Pin Set command
306  _pin,
307  11, // TM1637
308  blinkBitmapLSBleftDigit,
309  0x55,
310  0x55,
311  0x55,
312  0x55,
313  };
314  return _sw.sendPacket(tx_207);
315  }
316 
317 
318  /*
319  \brief Write a byte to String mode, shifting other characters
320 
321  This function allows the TM1637 mode to use Arduino Print statements.
322 
323  \param data Byte to be written to display
324  \return Number of bytes written
325 
326  */
327  size_t write(uint8_t data)
328  {
329  uint8_t tx[8] = {
330  (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE8, // Pin Set command
331  _pin,
332  PIN_MODE_TM1637, // TM1637
333  1,
334  data,
335  0x55,
336  0x55,
337  0x55,
338  };
339  if (_sw.sendPacket(tx) < 0)
340  {
341  return 0;
342  }
343  else
344  {
345  return 1;
346  }
347  }
348 
349  size_t write(const uint8_t* buffer, size_t size)
350  {
351  size_t initialSize = size;
352  if (size > 6)
353  {
354  buffer += size - 6;
355  size = 6;
356  }
357  if (size > 4)
358  {
359  uint8_t tx[8] = {
360  (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE8, // Pin Set command
361  _pin,
362  PIN_MODE_TM1637, // TM1637
363  4,
364  buffer[0],
365  buffer[1],
366  buffer[2],
367  buffer[3],
368  };
369  _sw.sendPacket(tx);
370  size -= 4;
371  buffer += 4;
372  }
373 
374  {
375  uint8_t tx[8] = {
376  (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE8, // Pin Set command
377  _pin,
378  PIN_MODE_TM1637, // TM1637
379  (uint8_t)size,
380  buffer[0],
381  size > 1 ? buffer[1] : (uint8_t)0x55,
382  size > 2 ? buffer[2] : (uint8_t)0x55,
383  size > 3 ? buffer[3] : (uint8_t)0x55,
384  };
385  _sw.sendPacket(tx);
386  }
387  return size_t(initialSize);
388  }
389 
390  virtual int availableForWrite() { return 100; } // We will throw out everthing but the last 6.
391  using Print::write;
392 
393 private:
394 
395  uint8_t _dioPin = 255;
396 };
397 
SerialWombatChip
Class for a Serial Wombat chip. Each Serial Wombat chip on a project should have its own instance.
Definition: SerialWombat.h:279
SerialWombatTM1637::write
size_t write(uint8_t data)
Definition: SerialWombatTM1637.h:327
SerialWombatTM1637::begin
int16_t begin(uint8_t clkPin, uint8_t dioPin, uint8_t digits, SWTM1637Mode mode, uint8_t dataSourcePin, uint8_t brightness0to7)
Initialize an instance of the TM1637 class.
Definition: SerialWombatTM1637.h:96
tm1637RawArray
@ tm1637RawArray
Display raw LED segments sent by the host.
Definition: SerialWombatTM1637.h:34
SerialWombatTM1637::writeDecimalBitmap
int16_t writeDecimalBitmap(uint8_t decimalBitmapLSBleftDigit)
Definition: SerialWombatTM1637.h:210
tm1637Animation
@ tm1637Animation
Definition: SerialWombatTM1637.h:35
SerialWombatTM1637::writeArray
int16_t writeArray(uint8_t data[6])
Definition: SerialWombatTM1637.h:168
SerialWombatPin::_sw
SerialWombatChip & _sw
Definition: SerialWombat.h:1566
SerialWombatTM1637::writeDigitOrder
int16_t writeDigitOrder(uint8_t first, uint8_t second, uint8_t third, uint8_t fourth, uint8_t fifth, uint8_t sixth)
Definition: SerialWombatTM1637.h:130
SerialWombatTM1637::SerialWombatTM1637
SerialWombatTM1637(SerialWombatChip &serialWombat)
Constructor for SerialWombatTM1637 class.
Definition: SerialWombatTM1637.h:81
PIN_MODE_TM1637
@ PIN_MODE_TM1637
(11)
Definition: SerialWombat.h:247
SerialWombatCommands::CONFIGURE_PIN_MODE8
@ CONFIGURE_PIN_MODE8
(208)
SerialWombatTM1637::writeAnimation
int16_t writeAnimation(uint16_t bufferIndex, uint16_t delay, uint8_t numberOfFrames, uint8_t data[][6])
Definition: SerialWombatTM1637.h:258
SerialWombatTM1637::writeBlinkBitmap
int16_t writeBlinkBitmap(uint8_t blinkBitmapLSBleftDigit)
Definition: SerialWombatTM1637.h:302
SerialWombat.h
SerialWombatTM1637::suppressLeadingZeros
int16_t suppressLeadingZeros(bool suppress)
Definition: SerialWombatTM1637.h:277
SerialWombatTM1637
A Class representing a TM1637 Seven-Segment Display connected to two Serial Wombat pins.
Definition: SerialWombatTM1637.h:74
tm1637CharArray
@ tm1637CharArray
Display a string sent by the host.
Definition: SerialWombatTM1637.h:33
SerialWombatPin
Describes a Serial Wombat Pin. Is base class for other pin modes.
Definition: SerialWombat.h:1470
SerialWombatTM1637::write
size_t write(const uint8_t *buffer, size_t size)
Definition: SerialWombatTM1637.h:349
SerialWombatChip::sendPacket
int sendPacket(uint8_t tx[], uint8_t rx[])
Send an 8 byte packet to the Serial Wombat chip and wait for 8 bytes back.
Definition: SerialWombat.cpp:139
SerialWombatChip::writeUserBuffer
int writeUserBuffer(uint16_t index, uint8_t *buffer, uint16_t count)
Write bytes to the User Memory Buffer in the Serial Wombat chip.
Definition: SerialWombat.h:1064
tm1637Decimal16
@ tm1637Decimal16
Get the number to display from a pin or data source and display in decimal.
Definition: SerialWombatTM1637.h:31
SerialWombatPin::_pin
uint8_t _pin
Definition: SerialWombat.h:1565
SerialWombatTM1637::writeBrightness
int16_t writeBrightness(uint8_t brightness0to7)
Definition: SerialWombatTM1637.h:231
SW_LE16
#define SW_LE16(_a)
Convert a uint16_t to two bytes in little endian format for array initialization.
Definition: SerialWombat.h:41
SerialWombatTM1637::availableForWrite
virtual int availableForWrite()
Definition: SerialWombatTM1637.h:390
SWTM1637Mode
SWTM1637Mode
Definition: SerialWombatTM1637.h:30
tm1637Hex16
@ tm1637Hex16
Get the number to display from a pin or data source and display in hex.
Definition: SerialWombatTM1637.h:32