mLink Arduino library for mLink modules

Useful guides, libraries, and example sketches to support our Arduino based products.
Post Reply
admin
Site Admin
Posts: 878
Joined: Sun Aug 05, 2012 4:02 pm

mLink Arduino library for mLink modules

Post by admin » Mon Oct 04, 2021 2:29 pm

Image



Arduino library for Hobby Components mLink range of modules. This library currently supports the following mLink products:

mLink 12 Bit port expander (SKU: HCMODU0180)
mLink DHT22 temperature and humidity sensor (SKU: HCMODU0181)
mLink 1 channel relay module (SKU: HCMODU0182)
mLink 2 channel relay module (SKU: HCMODU0183)
mLink 4 channel relay module (SKU: HCMODU0184)
mLink RGBW light controller (SKU: HCMODU0185)
mLink NTC temperature sensor (SKU: HCMODU0186)
mLink Matrix 4x4 keypad (SKU: HCMODU0188)
mLink 1602 & 2004 Character LCD (SKU: HCMODU0190A & HCMODU0190B)
mLink 12864 Graphics LCD (SKU: HCMODU0189)
mLink 6 Button Keypad (SKU: HCMODU0193)
mLink Home Sensor (SKU: HCMODU0198)
mLink TMP36 Temperature Sensor Module (SKU: HCMODU0187)
mLink L9110 DC Motor Controller (SKU: HCMODU0199)
mLink WS2812 RGB LED controller (HCMODU0197)
mLink LongReach LoRa Transceiver (HCMODU0250)


Using the mLink library


Step 1) Downloading the mLink library


The library is available via several sources:

1) The latest version of the library can be downloaded from our forum here: https://hobbycomponents.com/downloads/m ... V2_1_0.zip

2) Via our github page here: https://github.com/HobbyComponents/mLink

3) For PlatformIO users you can add the library to your project by going to the library section of PlatformIO and searching either 'hobbycomponents' to view a list of our libraries or 'mLink' to just list the mLink library.



Step 2) Installing the mLink Library to the Arduino IDE

Once downloaded, open up your Arduino IDE and go to Sketch->Include Library->Add .ZIP Library.

In the file selection dialogue window that opens up, navigate to wherever you downloaded the mLink .zip file and select it, then click the ‘Open’ button.

Alternatively you can just unzip the library into your Arduino library folder usually found in the following location:


On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/



Step 3) Including the mLink library in your sketch

Adding the mLink library to your sketch consists of 3 steps; Firstly, include the mLink header file (mLink.h) at the top of your sketch, create an instance of the library, then finally initialise the library inside the startup() function:

  1. // Step 1: Include the mLink library
  2. #include "mLink.h"
  3.  
  4.  
  5. //Step 2: Create an instance of the library
  6. mLink mLink;
  7.  
  8.  
  9. void setup()
  10. {
  11.   // Step 3: Initialise the library  
  12.   mLink.init();
  13. }
  14.  
  15.  
  16. void loop()
  17. {
  18. }

The mLink library can be used to control any type of mLink module. For specific instructions and example sketches for your mLink module please see the documentation in the products forum thread (https://hobbycomponents.com/mLink), or the example sketches found within the mLink library.



Library Functions

mLink DHT22
mlink.DHT22_Start(add)			// Triggers a new temp/hum measurement.
busy = mlink.DHT22_Busy			// Measurement in progress
temp= mlink.DHT22_Temp(add)		// Returns the temperature as a float in oC to 1dp
hum = mlink.DHT22_Hum(add)		// Returns the humidity as a float in RH% to 1dp

Where:
add = The I2C address of the module
busy = Returns true if there is a measurement in progress, false if measurement is complete
temp = A float containing the last temperature measurement in oC to 1dp.
hum = A float containing the last humidity measurement in %RH to 1dp.


mLink 1Ch, 2CH, & 4CH relays
mlink.SET_RLY0(add, state)		// Sets the state of relay 0
mlink.SET_RLY1(add, state)		// Sets the state of relay 1
mlink.SET_RLY2(add, state)		// Sets the state of relay 2
mlink.SET_RLY3(add, state)		// Sets the state of relay 3

state = mlink.READ_RLY0(add)		// Returns the state of relay 0
state = mlink.READ_RLY1(add)		// Returns the state of relay 1
state = mlink.READ_RLY2(add)		// Returns the state of relay 2
state = mlink.READ_RLY3(add)		// Returns the state of relay 3

mlink.RLY0_SetOnTime(add, time)	// Sets relay 0 on time in seconds
mlink.RLY1_SetOnTime(add, time)	// Sets relay 1 on time in seconds
mlink.RLY2_SetOnTime(add, time)	// Sets relay 2 on time in seconds
mlink.RLY3_SetOnTime(add, time)	// Sets relay 3 on time in seconds

Where:
add = The I2C address of the module
state = A boolean value (True / False) where True = Relay on, False = Relay off
time = A 16 bit integer containing the relay on time in seconds. 0 = timer disabled, 65535 = max


mLink NTC temperature sensor
temp = mlink.NTC_Temp(add) // Returns the temperature as a float in oC to 1dp

Where:
add = The I2C address of the module
temp = A float containing the last temperature measurement in oC to 1dp.


mLink 4x4 matrix keypad
key = mLink.read(add, KEYPAD_4X4_KEY)						// Returns the next key press from the buffer
state = mLink.Keypad_4x4_Key_Down(add)					// Returns True if a key is currently pressed, False if no key is pressed
mLink.write (KEYPAD_4X4_I2C_ADD , KEYPAD_4X4_DEBOUNCE , db);	// Sets the amount of key debouncing


Where:
add = The I2C address of the module
key = ASCII value of the last key pressed or 255 if no key has been pressed
state = A boolean value containing the key state. 0 = not pressed & 1 = currently pressed
db = The amount of debouncing required (max = 254)


mLink 1602 & 2004 Character LCD
mLink.cLCD_cursor(add, col, row)	// Sets the cursors column and row position
mLink.cLCD_clear(add)			// Clears the display
mLink.cLCD_on(add, state)		// Turns the display on or off 
mLink.cLCD_cursDir(add, dir)		// Sets the direction the cursor will move after printing a character
mLink.cLCD_dispType(add, type) 	// Sets the display size
mLink.cLCD_backlight(add, level)	// Sets the backlight brightness level
mLink.cLCD_contrast(add, level)	// Sets the contrast level
mLink.cLCD_print(add, text)		// Prints a string of text starting at the current cursor position
mLink.cLCD_printFloat(add, val, dp) 	// Prints a floating point number
mLink.cLCD_printCust(add, index)	// Writes one of the 8 custom characters to the display
mLink.cLCD_setCust0(add, bitmap)	// Writes a custom bitmap to custom character 0
mLink.cLCD_setCust1(add, bitmap)	// Writes a custom bitmap to custom character 1
mLink.cLCD_setCust2(add, bitmap)	// Writes a custom bitmap to custom character 2
mLink.cLCD_setCust3(add, bitmap)	// Writes a custom bitmap to custom character 3
mLink.cLCD_setCust4(add, bitmap)	// Writes a custom bitmap to custom character 4
mLink.cLCD_setCust5(add, bitmap)	// Writes a custom bitmap to custom character 5
mLink.cLCD_setCust6(add, bitmap)	// Writes a custom bitmap to custom character 6
mLink.cLCD_setCust7(add, bitmap)	// Writes a custom bitmap to custom character 7

Where:
add = The I2C address of the module
col = Cursor column position where 0 = left most column and 15 (1602) or 19 (2004) is right most column
row = Cursor row position where 0 = top row, 1 (1602) or 3 (2004) is the bottom row
text = A string of text to print to the screen
val = A floating point number
dp = the number of decimal places to print val to
state = Display on / off state where 0 = off and 1 = on
dir = Cursor direction where direction = 0 is left to right and direction = 1 is right
type = Display type where 0 = 16x2 line display and 1 = 20x4 line display
level = Backlight level where 0 = off and 10 = max
Contrast = Contrast level where 0 = min, 255 = max
index = The index (0 to 7) of the custom character to print
bitmap = An array of 8 bytes containing the custom character bitmap to upload. See documentation for how to define a bitmap


mLink TMP36 Temperature Sensor
temp = mLink.TMP36_Temp(add)	// Returns the current temperature

Where
add = The I2C address of the module
temp = The current temperature in oC to 1 decimal place

mLink 6 button pad
mLink.bPad_Empty(add)				// Returns the state of the buffer where True = buffer empty, False = buffer contains one or more keys
mLink.bPad_Read(add)				// Returns the next key from the buffer
mLink.bPad_UpState(add)				// Returns True if the Up key is currently pressed, False if not
mLink.bPad_LeftState(add)			// Returns True if the Left key is currently pressed, False if not
mLink.bPad_DownState(add)			// Returns True if the Down key is currently pressed, False if not
mLink.bPad_RightState(add)			// Returns True if the Right key is currently pressed, False if not
mLink.bPad_SelectState(add)			// Returns True if the Select key is currently pressed, False if not
mLink.bPad_BackState(add)			// Returns True if the Back key is currently pressed, False if not
mLink.bPad_Debounce(add, debounce)	// Sets the amount of debouncing

Where:
add = The I2C address of the module
debounce = The level of debouncing to apply to each keypress where 0 is none, 254 is max


mLink home sensor
mLink.HSense_Start_Meas(add)		// Triggers the start of a new temperature/humidity, use ml.busy(add) to test when measurement is complete
mLink.HSens_Temp(add)			// Returns the temperature in oC as a floating point value to 1dp
mLink.HSens_Hum(add)			// Returns the humidity in RH% as a floating point value to 1dp
mLink.HSens_DHT22_Error(add)		// Returns true if the current measurement was read from the DHT22 was valid, false if there was an error
mLink.HSens_LDR(add)			// Returns a light level sensed by the LDR sensor where 0 = dark and 255 = maximum brightness
mLink.HSens_PIR(add)			// Returns a light level sensed by the LDR sensor where 0 = dark and 255 = maximum brightness
mLink.HSens_Trigs(add)			// Returns a 16 bit integer containing the amount of times the PIR sensor has been triggered since last reset
mLink.HSens_Clear_Trigs(add)		// Resets the PIR trigger counter
mLink.HSense_Start_Meas(add)		// Triggers the start of a new temperature/humidity, use mLink.busy(add) to test when measurement is complete

Where:
add = The I2C address of the module


mLink NEC IR Transceiver
mLink.IR_Write_Data(add, data)			// Writes a 4 byte list to the Tx buffer
mLink.IR_Write_NEC(add, iradd, irdat)		// Writes an NEC address and command to the Tx buffer for transmitting
rxcount =  mLink.IR_Count(add)				// Returns the amount of times an IR message (inc repeat codes) has been received
valid = mLink.IR_NEC_Valid(add)			// Returns true if the last message received was a valid NEC message
mLink.IR_Read(add, data)					// Returns the last message received as a 4 byte list
iradd =mLink.IR_Read_NEC_Add(add)			// Returns the NEC address byte from a received IR message
irdat = mLink.IR_Read_NEC_Command(add)	// Returns the NEC command byte from a received IR message
mLink.IR_Send(add, count)				// Triggers a transmit of the message stored in the Tx buffer
mLink.IR_Com_LED_Mode(add, mode)		// Sets the mode of the COM LED

Where:
add = The I2C address of the module
iradd = NEC IR address byte
irdat = NEC IR command byte
count = Amount of times to transmit the message including repeat codes. Valid values are:
	If count = 1 then the message will be transmitted once
	If count = 1 + n then the message will be transmitted once + n x repeat codes
	If count = 255 then a single repeat code will be sent


data = a list of 4 bytes containing the IR message
mode = The required LED mode. Valid values are:
	IR_COM_LED_I2C = LED will illuminate during I2C bus transfers
	IR_COM_LED_IR = LED will illuminate whilst IR data is being received or transmitted


rxcount = The amount of times, including repeat codes, the IR message was received
valid = last received code was a valid NEC message


mLink L9110 DC Motor Controller
mLink.L9110_M1_Speed(add, speed)		// Sets the speed of motor M1
mLink.L9110_M2_Speed(add, speed)		// Sets the speed of motor M2
mLink.L9110_M1_Dir(add, dir)			// Sets the direction of motor M1
mLink.L9110_M2_Dir(add, dir)			// Sets the direction of motor M2
mLink.L9110_M1_Stop(add)			// Stops motor M1
mLink.L9110_M2_Stop(add)			// Stops motor M2

Where:
add = The I2C address of the module
speed = A value between 0 and 255 that sets the speed of the motor
direction = Sets the direction of rotation. Valid values are:
	REVERSE
	FORWARD



mLink WS2812 RGB LED Controller
mLink.WS2812_Max(add, maxIndex)			// Sets the number of LEDs connected
mLink.WS2812_Index(add, ledIndex)			// Sets the index of the LED to modify
mLink.WS2812_Red(add, redLevel)			// Sets the red level of the selected LED
mLink.WS2812_Green(add, greenLevel)		// Sets the green level of the connected LED
mLink.WS2812_Blue(add, blueLevel)			// Sets the blue level of the connected LED
mLink.WS2812_Refresh(add)				// Writes the buffer to the LEDs
mLink.WS2812_Clear(add)					// Sets the RGB levels off all leds to 0 (off)
mLink.WS2812_Brightness(add, bri)			// Sets the maximum brightness of the LEDs
mLink.WS2812_On(add, state)				// Turns all LEDs on or off
mLink.WS2812_Order(add, order)			// Sets the RGB order of the LEDs
mLink.WS2812_RGB(add, index, redLevel, greenLevel, blueLevel)	// Sets the RGB levels of an LED
redLevel = mLink.WS2812_Get_Red(add)		// Gets the current red level of the selected LED
greenLevel = mLink.WS2812_Get_Green(add)	// Gets the current green level of the selected LED
blueLevel = mLink.WS2812_Get_Blue(add)		// Gets the blue level of the selected LED
bri = mLink.WS2812_Get_Brightness(add)		// Gets the current brightness
state = mLink.WS2812_Get_On_State(add)		// Gets the on/off state of the LEDs

Where:
add = The I2C address of the module
maxIndex = The number of LEDs in your strip/module
ledIndex = The index of the LED to adjust
redLevel = The red level (0 to 255) of the LED at index ledIndex
greenLevel = The green level (0 to 255) of the LED at index ledIndex
blueLevel = The blue level (0 to 255) of the LED at index ledIndex
bri = The maximum brightness level (0 to 255) of the LED at index ledIndex
state = The on/off state of the LEDs. Valid values are
	0 = LEDs off
	1 = LEDs on


order = The RGB order of your LED strip. Valid values are:
	WS2812_ORDER_RGB (0)
	WS2812_ORDER_GRB (1)



mLink LongReach RM95 LoRa Transceiver
avail = mLink.LORA_Rx_Available(add)	// Checks to see if there is new Rx data available
size = mLink.LORA_Rx_Size(add)		// Gets the size of the received data
mLink.LORA_Rx_Read(add, size, rxarray)	// Reads the received data out of the Rx buffer
mLink.LORA_Rx_Address(add)			// Gets the address of the last received LongReach packet
mLink.LORA_Tx_Load(add, size, txarray)	// Loads data into the Tx buffer
mLink.LORA_Tx_Send(add)			// Sends the data in the Tx buffer
mLink.LORA_Tx_LR_Send(add, lrAdd)		// Sends the data in the Tx buffer as a LongReach packet
done = mLink.LORA_Tx_Done(add)		// Checks to see if the module has finished transmitting
mLink.LORA_Freq(add, freq)			// Sets the Tx/Rx frequency
mLink.LORA_Set_BW(add, bw)			// Sets the bandwidth
mLink.LORA_Set_SF(add, sf)			// Sets the spreading factor
rssi = mLink.LORA_RSSI(add)			// Returns the RSSI of the last received data
mLink.LORA_LR_Mode(add, lrmode)		// Enables/disables LongReach mode
mLink.LORA_Mode(add, mode)			// Changed the current radio mode
mLink.LORA_Resends(add, resends)		// Sets the amount of retransmits
mLink.LORA_Resend_Delay(add, delay)	// Sets the delay time between each resend

Where:
add = The I2C address of the module
size = The size in bytes of the data
rxarray = A byte array big enough to hold the received data
txarray = A byte array containing the data to be loaded into the Tx buffer
lrAdd = In LongReach mode this is the destination address the data will be sent to. In normal mode this is unused and can be any value.
freq = A unsigned in value containing the frequency in MHz
Bw = A byte value containing the bandwidth. Valid values are:
	LORA_BW_7_8KHz	(0)
	LORA_BW_10_4KHz	(1)
	LORA_BW_15_6KHz	(2)
	LORA_BW_20_8KHz	(3)
	LORA_BW_31_25KHz	(4)
	LORA_BW_41_7KHz	(5)
	LORA_BW_62_5KHz	(6)
	LORA_BW_125KHz	(7)
	LORA_BW_250KHz	(8)
	LORA_BW_500KHz	(9)


sf = A byte value containing the spreading factor. Valid values are:
	LORA_SF_64	(6)
	LORA_SF_128	(7)
	LORA_SF_256	(8)
	LORA_SF_512	(9)
	LORA_SF_1024	(10)
	LORA_SF_2048	(11)
	LORA_SF_4096	(12)


lrmode = The LongReach mode where 0 = disabled (normal), 1 = enabled (LongReach mode)
mode = A byte value representing the required radio mode. Valid value for mode are:
	LORA_MODE_SLEEP
	LORA_MODE_STDBY
	LORA_MODE_TRANSMIT
	LORA_MODE_RXCONTINUOUS
	LORA_MODE_RXSINGLE


resends = A byte value containing the number of resend (max = 10)
delay = An unsigned int containing the resend delay time in milliseconds (min = 100, max = 65535)




Diagrams, libraries, and example code are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no provide any guarantees or warranties as to their accuracy or fitness for purpose.

Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.

Post Reply

Return to “Arduino”