megunolink library ugww1.microchip.com/downloads/en/devicedoc/megunolink... · all documentation...

MegunoLink Library User'sGuide

MegunoLink Protocol (MLP) Library Module for MPLAB® XCode Configurator User's Guide

Preface

Important: Notice to customers:All documentation becomes dated, and this manual is no exception. Microchip tools anddocumentation are constantly evolving to meet customer needs, so some actual dialogs and/ortool descriptions may differ from those in this document. Please refer to our website(www.microchip.com) to obtain the latest documentation available.

Documents are identified with a “DS” number. This number is located on the bottom of eachpage, in front of the page number. The numbering convention for the DS number is“DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of thedocument.

For the most up-to-date information on development tools, see the MPLAB® IDE online help.Select the Help menu, and then Topics to open a list of available online help files.

IntroductionThis document describes how to use the MegunoLink Protocol Library (MLP), and includes a simpleexample application using MPLAB® X Code Configurator (MCC) and MegunoLink.

Overview

The MegunoLink Protocol (MLP) Library Module for MPLAB® X Code Configurator allows for quick andeasy C code generation for interfacing with MegunoLink visualizers.

This library module uses a Graphical User Interface (GUI) to accomplish the following:• Enabling multiple MegunoLink visualizers• Setting various Communication Interface• Generating the necessary C code to program onto a PIC® microcontroller

This user’s guide cover each component of the MLP library module, and how to setup a basic MLPproject.

© 2019 Microchip Technology Inc. User Guide DS40002081A-page 1

Table of Contents

Preface............................................................................................................................ 1

Overview..........................................................................................................................1

1. MLP Library Module.................................................................................................. 41.1. Installing MLP Library...................................................................................................................41.2. MLP Library..................................................................................................................................4

2. MLP Library Module API............................................................................................92.1. Command Handler....................................................................................................................... 92.2. Command Parameters................................................................................................................. 92.3. Interface Panel............................................................................................................................. 92.4. Map............................................................................................................................................ 102.5. Message Monitor........................................................................................................................102.6. Table...........................................................................................................................................102.7. Test Report................................................................................................................................. 112.8. Time Plot.....................................................................................................................................112.9. X-Y Plot...................................................................................................................................... 112.10. MLP Update................................................................................................................................11

3. Quick Setup for MegunoLink Library Project........................................................... 12

4. MegunoLink Setup...................................................................................................194.1. Setting Up Visualizers................................................................................................................ 194.2. Connecting the Device with MegunoLink................................................................................... 19

5. MLP Example.......................................................................................................... 215.1. Included Files............................................................................................................................. 215.2. TestPrintFunctions......................................................................................................................215.3. TestTableFunctions.....................................................................................................................225.4. TestTimePlotFunctions............................................................................................................... 235.5. TestXYPlotFunctions.................................................................................................................. 255.6. TestMessageMonitor.................................................................................................................. 265.7. TestInterfacePanel......................................................................................................................285.8. TestMap......................................................................................................................................315.9. TestTestReport........................................................................................................................... 325.10. CheckParameter........................................................................................................................ 335.11. TestValueParsing........................................................................................................................335.12. Cmd_Set.................................................................................................................................... 345.13. Update........................................................................................................................................345.14. MLP_Example............................................................................................................................35

6. Revision History.......................................................................................................36

The Microchip Web Site................................................................................................ 37

MegunoLink Library User's Guide


Customer Change Notification Service..........................................................................37

Customer Support......................................................................................................... 37

Microchip Devices Code Protection Feature................................................................. 37

Legal Notice...................................................................................................................38

Trademarks................................................................................................................... 38

Quality Management System Certified by DNV.............................................................39

Worldwide Sales and Service........................................................................................40



1. MLP Library ModuleThis chapter provides step-by-step instructions for installing the MLP Library Plug-in for MPLAB® X CodeConfigurator. This chapter also provides explanation for the different parts of the library.

1.1 Installing MLP Library1. Install MPLAB® Code Configurator2. Add MLP Library Plug-in to MCC:

1. In MPLAB® X IDE click on Tools > Options2. Click on Plug-ins tab3. Click on Install Library4. Browse to the location of the MLP Library Plug-in, select it and click Open.

1.2 MLP LibraryThe MegunoLink Protocol (MLP) Library module (Figure 1-1) is split into two tabs:

1. Information Tab - displays the description about MegunoLink and a link to its product page.Figure 1-1. MegunoLink Information Tab

2. Configuration Tab - displays the configuration for the peripherals and visualizer used in the library.

MegunoLink Library User's GuideMLP Library Module


https://www.microchip.com/mplab/mplab-code-configurator

Figure 1-2. MegunoLink Configuration Tab

The Configuration tab (Figure 1-2) contains five areas that are accessed by expanding thedifferent panes. The five sections are:

1. Communication Interface2. UART Settings3. Timer Settings4. MegunoLink Visualizers5. Example

The following sub-chapters provide details about the contents of each area.

1.2.1 Communication InterfaceThe Communication Interface area contains options for selecting a communication interface tocommunicate with MegunoLink as shown in Figure 1-3. Only those interfaces supported by MCC willappear in the options. Please refer to the ‘Release Notes’ for supported interfaces for each releaseversion of the library.Figure 1-3. Communication Interface



1.2.2 UART SettingsThe UART Settings area (Figure 1-4) allows the user to select a specific UART instance and set therequired baud rate for communication.Figure 1-4. UART Settings

1.2.3 Timer SettingsThe Timer Settings area (Figure 1-5) allows the user to choose an available hardware timer to be used forthe trigger period of the functions.Figure 1-5. Timer Settings

1.2.4 MegunoLink VisualizersThe MegunoLink Visualizers area (Figure 1-6) allows the user to enable/disable the available MegunoLinkdata visualizer functions. The details for each visualizer are provided below.



Figure 1-6. MegunoLink Visualizers

1. ENABLE ALL VISUALIZERSThe Enable All Visualizers check box in the MegunoLink Visualizers area allows the module togenerate all visualizer functions. When checked, the visualizers are all selected and their checkboxes are disabled.

2. VISUALIZERS AREAThe user also has an option of generating only the visualizer functions required by their applicationby checking the individual check boxes in the Visualizers area. The Visualizers area consists of thedifferent visualizers available in the MegunoLink Interface:1. Interface Panel

The Interface Panel lets the user control the microcontroller with virtual controls sendingserial commands. The Interface Panel controls can trigger measurements, startexperiments, configure user’s creation and retrieve information from a program.

2. MapThe Mapping visualizer lets the user collect location data from GPS sensors and report iton a map displaying a visual representation of the reported location.

3. Message MonitorThe Message Monitor extracts specially tagged text from the serial stream. It lets the userpull out logs, specific data or messages from all the other serial data.

4. TableThe Table visualizer lists name/value pairs in a table. MegunoLink continuously looks atdata in the serial stream from the microcontroller for specially formatted commands topopulate the table.

5. Test ReportThe Program Device Visualizer’s Test Report Panel can be used to report pass/fail resultsfrom self-test code running on the microcontroller.

6. Time Plot



The Time Plot visualizer sends measurements from microcontroller to MegunoLink forplotting. Time plots are useful for testing new sensors such as accelerometers,temperature, force and many more.

7. X-Y PlotThe X-Y Plot visualizer lets the user send X-Y pairs through the microcontroller’s serial portto view plots of the data.

1.2.5 ExampleThe Example area (Figure 1-7) allows users to generate an example file that includes the test functionsfor communicating with MegunoLink visualizers.Figure 1-7. Example Area



2. MLP Library Module APIThe MLP Library is customized and generated by MCC based on the settings configured by the user inthe MegunoLink GUI. The generated library functions will be called by the user application to be able toestablish communication with MegunoLink.

2.1 Command HandlerThe Command Handler buffers serial data, detects and processes commands.

CH_InitInitializes the command handler data. The context must be initialized before it canbe used.

CH_AddCommandAdds a new command to the context and binds it to a callback.

CH_ProcessReads characters from the serial stream, detect and dispatch commands as theyencountered.

2.2 Command ParametersThe following functions extract the parameters from command strings.CH_NextParameter

Retreives the next parameter supplied with the command.

CH_NextParameterAsXXRetrieves the next command parameter, converting it to a typed indicated by XX. Itreturns a default value if the parameter is missing or invalid.

2.3 Interface PanelThe following functions update a control on a MegunoLink Interface Panel visualizer.

• IP_CallCommand• IP_EnableControl• IP_DisableControl• IP_ShowControl• IP_HideControl• IP_SetForeColor• IP_SetBackColor• IP_SetCheck• IP_SetProgress• IP_SetReadOnly• IP_GetValue

The following functions set the selected item in a ValueList control based on the type indicated:

MegunoLink Library User's GuideMLP Library Module API


• IP_SetListIndex• IP_SetListName• IP_SetListValue

The following functions update the value for a NumericUpDown, ProgressBar, or TrackBarWithIndicatorcontrol:

• IP_SetMaximum• IP_SetMinimum

The following functions set the numeric value displayed by a control:• IP_SetNumber_Double• IP_SetNumber_Int• IP_SetNumber_Long• IP_SetNumber_Unsigned_Long

The following functions update control text to a type indicated:• IP_SetText_Double• IP_SetText_Int• IP_SetText_Long• IP_SetText_String• IP_SetText_Unsigned_Long

2.4 MapThe following functions send latitude and longitude data to a MegunoLink Map visualizer:

• Map_Send_Double• Map_Send_String

2.5 Message MonitorThe following functions send data to a MegunoLink Message Monitor. Text sent to the Message Monitorcan be read aloud by MegunoLink using the system speech synthesizer.

Message_BeginStarts sending text to a Message Monitor.

Message_BeginExStarts sending text to a Message Monitor. The content can be optionally displayedas text or spoken by the system’s built-in speech synthesizer.

These functions send an array of value with the type indicated separated by commas:• Message_Send_CSV_Int• Message_Send_CSV_Unsigned

2.6 TableThe following functions send row data to a MegunoLink Table visualizer:



• Table_ClearRow• Table_GetData• Table_SetDescription• Table_ShowCurrentTime

These functions set the value of the named row with the type indicated:• Table_Send_Int• Table_Send_String• Table_Send_Unsigned

2.7 Test ReportThe following functions send data to a MegunoLink Test Report:Test_ReportResult

Reports a pass/fail test result to a test panel on a Programmer visualizer; the resultwill be shown in the TestResult column.

These functions report a test result to a test panel with the type indicated:• Test_ReportResult_Int• Test_ReportResult_Long• Test_ReportResult_Unsigned• Test_ReportResult_Unsigned_Long

2.8 Time PlotThe following functions send data with the type indicated to a MegunoLink Time Plot visualizer:

• TimePlot_Send_Int• TimePlot_Send_Long

2.9 X-Y PlotThe following functions send data with the type indicated to a MegunoLink X-Y Plot visualizer:

• XYPlot_Send_Int• XYPlot_Send_Long

2.10 MLP UpdateThe following functions are used to send a periodic update of the visualizer messages to Megunolink:

• MLPUpdate_Initialize• MLP_SetUpdate• MLP_Refresh



3. Quick Setup for MegunoLink Library ProjectThis chapter provides step-by-step instructions for creating and programming a basic MLP project onto aPIC® microcontroller.

A PIC16F18857 is used for this example project, but the same steps will work with any PICmicrocontroller with UART.Note: Your PIC device should have at least 28KB of available program memory. Loading this library intodevices with lower program memory may result in out of memory and compilation errors. This libraryconsumes about 19KB of program memory. So it is advisable to use a microcontroller with higherprogram memory for various applications with high memory usage.

The example project includes the following:• Test messages for each visualizer• Configured UART• Configured TIMER

1. Start MCC configuration by setting up the System Module, as shown in Figure 3-1.Figure 3-1. System Module

MegunoLink Library User's GuideQuick Setup for MegunoLink Library Project


For this example, PICkit ™3 In-circuit Debugger was used for programming the PIC microcontroller.2. Select MLP Library by going to Libraries > MLP > MegunoLink from the Device Resources

Panel (Figure 3-2).Figure 3-2. MLP Library Module in Device Resources

The MLP Library, together with the default UART and Timer, are automatically added to the ProjectResources panel (Figure 3-3).Figure 3-3. Peripheral Module

3. Configure the UART TX and RX pins from the Pin Manager: Grid View as shown in Figure 3-4.



Figure 3-4. Pin Manager

For this example, pins RC6 and RC7 are used.4. In the MegunoLink GUI, select the UART instance, UART baud rate, and Timer instance, as shown

in Figure 3-5:Figure 3-5. UART and Timer Configuration

5. Check the Enable All Visualizers check box as shown in Figure 3-6.The MegunoLink Visualizers Pane lets the user select which visualizer to use.



Figure 3-6. MegunoLink Visualizers

Note: When the Enable All Visualizers check box is checked, all the visualizers are alsoselected.

6. Generate the example of the Library by checking the Generate Example check box as shown in Figure 3-7.Figure 3-7. Example



7. Setup the UART module by configuring the EUSART as shown in Figure 3-8.Figure 3-8. UART Configuration

To use the printf function and send string to EUSART, the EUSART module needs to beredirected to STDIO.

8. Set up the Timer module by setting the period, interrupt, and clock source as shown in Figure 3-9.



Figure 3-9. Timer Configuration

– Set the period to 1 ms– Select FOSC/4 as clock source– Enable Tmer Interrupt– Set Callback Function Rate to 1 ms

9. To generate code, click the Generate button next to Project Resources as shown in Figure 3-10.Figure 3-10. Generate Code

10. Add code to the Application’s main loop1. Include the MLPExample.h in the main.c file:



Figure 3-11. Header

2. Add the MLP_Example function onto the main loop.The global and peripheral interrupt must be enabled for the timer as shown in Figure 3-12.Figure 3-12. Main Loop

At this point, the MLP configuration is complete.



4. MegunoLink SetupThis chapter will show how to setup a basic project in MegunoLink that will communicate with the targetPIC microcontroller described in 3. Quick Setup for MegunoLink Library Project.

It is assumed that the MegunoLink application is already installed in your machine. For more informationon how to install MegunoLink, please visit the MegunoLink website.

4.1 Setting Up VisualizersVisualizers interpret commands to plot data, change controls, update tables, and display messages. Forthe documentation, visit the MegunoLink website.Figure 4-1. MegunoLink Test Interface

Configure the MegunoLink test interface as shown in Figure 4-1. Each of the red labels is the name ofthat particular Visualizer.

4.2 Connecting the Device with MegunoLinkSelect the correct COM port and Baud Rate of your device in the Connection Manager then clickConnect as shown in Figure 4-2.

MegunoLink Library User's GuideMegunoLink Setup


https://www.megunolink.com/documentation/installing-megunolink/https://www.megunolink.com/documentation/what-is-a-visualizer/

Figure 4-2. Connection Manager

Figure 4-3 shows sample test messages and response on each data visualizer.Figure 4-3. MegunoLink Interaction

The next section will teach you how to implement the MCC-generated MLP Library functions tocommunicate and display messages on each of the MegunoLink visualizers.

MegunoLink Library User's GuideMegunoLink Setup


5. MLP ExampleThis chapter includes sample code written in C for each visualizer, with the Test Messages and theircorresponding displays in the MegunoLink.

5.1 Included Files

/**Section: Included Files*/

#include "MLP_Example.h"

5.2 TestPrintFunctionsThe TestPrintFunction sends data in different types and values using both the printf function andthe MegunoLinkProtocol.

void TestPrintFunctions() { printf("\n\n--- Test Printing Types ---\n"); printf("Print positive integer (1234): "); MLP_Print_Int(1234); printf("\n");

printf("Print negative integer (-1234): "); MLP_Print_Int(-1234); printf("\n"); printf("Print positive max integer (32767): "); MLP_Print_Int(INT_MAX); printf("\n"); printf("Print negative min integer (-32768): "); MLP_Print_Int(INT_MIN); printf("\n"); printf("Print 0 integer (0): "); MLP_Print_Int(0); printf("\n"); printf("--- MLP_Print_Long---\n"); printf("Print positive integer (1234): "); MLP_Print_Long(1234); printf("\n"); printf("Print negative integer (-1234): "); MLP_Print_Long(-1234); printf("\n"); printf("Print positive max integer (LONG_MAX): "); MLP_Print_Long(LONG_MAX); printf("\n"); printf("Print negative min integer (LONG_MIN): "); MLP_Print_Long(LONG_MIN); printf("\n"); printf("Print 0 integer (0): "); MLP_Print_Long(0); printf("\n"); printf("--- MLP_Print_UInt---\n"); printf("Print positive integer (1234): ");

MegunoLink Library User's GuideMLP Example


MLP_Print_UInt(1234); printf("\n"); printf("Print positive max integer (65535): "); MLP_Print_UInt(UINT_MAX); printf("\n"); printf("Print 0 integer (0): "); MLP_Print_UInt(0); printf("\n"); printf("--- MLP_Print_ULong---\n"); printf("Print positive integer (1234): "); MLP_Print_ULong(1234); printf("\n"); printf("Print positive max integer (4294967295): "); MLP_Print_ULong(ULONG_MAX); printf("\n");

The TestPrintFunctions message is displayed in the Serial Monitor as shown in Figure 5-1Figure 5-1. Test Printing Types

5.3 TestTableFunctionsThe TestTableFunction provides an example on how to use the Table visualizer.

void TestTableFunctions() { printf("\n\n--- Table Test ---\n"); Table_Send_Int("Row 1", 10); Table_Send_Unsigned("Row 2", 2); Table_Send_String("Row 3", "I am not a fish"); Table_ShowCurrentTime("Row 4"); Table_SetDescription("Row 5", "This is a description"); Table_ClearRow("Row 5"); Table_GetData("Row 3"); //Table_ClearAllRows();



printf("\n"); printf("\n");}

Formatted commands sent from the microcontroller to populate the tables are displayed in the SerialMonitor as shown in Figure 5-2.

Figure 5-2. Table Test from Serial Monitor

The data is displayed in the Table visualizer as shown in Figure 5-3.Figure 5-3. Table Test from Table Visualizer

5.4 TestTimePlotFunctionsThe TestTimePlotFunction provides an example on how to use the Time Plot visualizer.

void TestTimePlotFunctions() { printf("\n\n--- Time Plot Test ---\n"); TimePlot_Send_Int("Series 1", 10); TimePlot_Send_Long("Series 2", 20); TimePlot_Send_Double("Series 3", 5.78); TimePlot_SetTitle("My Title"); TimePlot_SetXLabel("X Label"); TimePlot_SetYLabel("Y Label"); TimePlot_SetSeriesProperties("Series 3", CLR_Red, LINE_Solid, 2, MARKER_Circle);



TimePlot_SetSeriesProperties_String("Series 4", "ro"); //TimePlot_Clear("Series 2"); //TimePlot_ClearAll();


Commands sent from the microcontroller to set the graph titles, style and data to Time Plot Visualizer aredisplayed in the Serial Monitor as shown in Figure 5-4.Figure 5-4. Time Plot Test from Serial Monitor

Data plotted in the Time Plot Visualizer are shown in Figure 5-5.Figure 5-5. Time Plot Visualizer



5.5 TestXYPlotFunctionsThe TestXYPlotFunction provides an example on how to use the X-Y Plot visualizer.

void TestXYPlotFunctions() { printf("\n\n--- XY Plot Test ---\n"); XYPlot_Send_Int("Series 1", 1, 10); XYPlot_Send_Long("Series 2", 3, 20); XYPlot_Send_Double("Series 3", 4.1, 5.78); XYPlot_SetTitle("My Title"); XYPlot_SetXLabel("X Label"); XYPlot_SetYLabel("Y Label"); XYPlot_SetSeriesProperties("Series 3", CLR_Red, LINE_Solid, 2, MARKER_Circle); XYPlot_SetSeriesProperties_String("Series 4", "ro"); //XYPlot_Clear("Series 2"); //XYPlot_ClearAll();


Commands sent from the microcontroller to set the graph titles, style and data on X-Y Plot Visualizer aredisplayed in the Serial Monitor as shown in Figure 5-6.Figure 5-6. X-Y Plot Test from Serial Monitor

Data plotted in the X-Y Plot Visualizer are shown in Figure 5-7.



Figure 5-7. X-Y Plot Visualizer

5.6 TestMessageMonitorThe TestMessageMonitor function provides an example on how to use the Message Monitor.

void TestMessageMonitor() { printf("\n\n--- Message Monitor Test ---\n"); Message_Begin(); Message_Send_Int(12); Message_Send_String(" - "); Message_Send_Unsigned(22); Message_Send_String(" - "); Message_Send_Long(123); Message_Send_String(" - "); Message_Send_Unsigned_Long(12234); Message_End();

int anData[] = {-1, 2, -3, 4}; Message_Begin(); Message_Send_CSV_Int(anData, sizeof (anData) / sizeof (anData[0])); Message_End();

unsigned int auData[] = {1, 2, 3, 4}; Message_Begin(); Message_Send_CSV_Unsigned(auData, sizeof (auData) / sizeof (auData[0])); Message_End();

Message_BeginEx(false, true); // text=false, speak=true Message_Send_Int(12); Message_Send_String(" - "); Message_Send_Unsigned(22); Message_Send_String(" - "); Message_Send_Long(123); Message_Send_String(" - "); Message_Send_Unsigned_Long(12234);



Message_End();

Message_BeginEx(true, true); //text=true, speak=true Message_Send_Int(13); Message_Send_String(" - "); Message_Send_Unsigned(14); Message_Send_String(" - "); Message_Send_Long(14); Message_Send_String(" - "); Message_Send_Unsigned_Long(15); Message_End();

}

Commands sent from the microcontroller to send message to the Message Monitor Visualizer aredisplayed in the Serial Monitor as shown in Figure 5-8.Figure 5-8. Message Monitor Test from Serial Monitor

Message extracted from the Serial Monitor are displayed in Message Monitor Visualizer as shown in Figure 5-9.



Figure 5-9. Message Monitor Visualizer

5.7 TestInterfacePanelThe TestInterfacePanel function provides an example on how to use the Interface Panel.

void TestInterfacePanel() { printf("\n\n--- Interface Panel Test ---\n"); IP_SetText_String("IPTextBox1", "Hello"); __delay_ms(500); IP_SetText_Int("IPTextBox1", 1); __delay_ms(500); IP_SetText_Long("IPTextBox1", 2); __delay_ms(500); IP_SetText_Unsigned_Long("IPTextBox1", 3);

IP_SetNumber_Double("IPNumericUpDown1", 12.3); __delay_ms(500); IP_SetNumber_Double("IPNumericUpDown1", 5.1); __delay_ms(500); IP_SetNumber_Double("IPNumericUpDown1", 22.3);

IP_SetProgress("IPProgressBar1", 12); __delay_ms(500); IP_SetProgress("IPProgressBar1", 30);

IP_SetNumber_Int("TrackBarWithIndicator1", 10); __delay_ms(500); IP_SetNumber_Long("TrackBarWithIndicator1", 12); __delay_ms(500); IP_SetNumber_Unsigned_Long("TrackBarWithIndicator1", 14); __delay_ms(500);

IP_SetListIndex("IPValueList1", 1); __delay_ms(500); IP_SetListValue("IPValueList1", 2);



__delay_ms(500); IP_SetListName("IPValueList1", "fish");

IP_SetCheck("IPCheckBox1", true); __delay_ms(500); IP_SetCheck("IPCheckBox1", false); __delay_ms(500); IP_SetCheck("IPCheckBox1", true); __delay_ms(500); IP_SetCheck("IPCheckBox1", false); __delay_ms(500);

IP_ShowControl("IPPictureBox1"); __delay_ms(500); IP_HideControl("IPPictureBox1"); __delay_ms(500); IP_ShowControl("IPPictureBox1"); __delay_ms(500); IP_HideControl("IPPictureBox1");

IP_EnableControl("IPButton1"); __delay_ms(500); IP_DisableControl("IPButton1"); __delay_ms(500); IP_EnableControl("IPButton1"); __delay_ms(500);

IP_SetForeColor("IPTextBox1", "red"); __delay_ms(500); IP_SetForeColor("IPTextBox1", "black"); __delay_ms(500);

IP_SetBackColor("IPTextBox1", "blue"); __delay_ms(500); IP_SetBackColor("IPTextBox1", "white");

IP_CallCommand("MyCommand"); __delay_ms(500);

IP_GetValue("IPTextBox1", "Text"); //control name, property name __delay_ms(500); IP_SetReadOnly("IPTextBox1", true); __delay_ms(500); IP_SetReadOnly("IPTextBox1", false); __delay_ms(500); IP_SetReadOnly("IPTextBox1", true); __delay_ms(500);

IP_SetMinimum("TrackBarWithIndicator1", 2); __delay_ms(500); IP_SetMaximum("TrackBarWithIndicator1", 50); __delay_ms(500);}

Commands sent from the microcontroller to send message to the Interface Panel Visualizer are displayedin the Serial Monitor as shown in Figure 5-10.



Figure 5-10. Interface Panel Test from Serial Monitor

Message extracted from the Serial Monitor are displayed in Interface Panel Visualizer as shown in Figure5-11.



Figure 5-11. Interface Panel Visualizer

5.8 TestMapThe TestMap function provides an example on how to use the Map visualizer.

void TestMap() { printf("\n\n--- Mapping Test ---\n"); Map_Send_String("Home1", "-37.8066187", "175.3291289"); Map_Send_Double("Home2", -37.8066187, 175.3291289);}

Commands sent from the microcontroller to send message to the Map Visualizer are displayed in theSerial Monitor as shown in Figure 5-12.Figure 5-12. Mapping Test from Serial Monitor

Coordinates of the place are displayed in Map Visualizer as shown in Figure 5-13.



Figure 5-13. Map Visualizer

5.9 TestTestReportThe TestTestReport function provides an example on how to use the Test Panel on ProgramVisualizer.

void TestTestReport() { printf("\n\n--- Test Report ---\n"); Test_ReportResult(1, true); Test_ReportResult_String(2, false, "Failed test"); Test_ReportResult_Int(3, true, 3); Test_ReportResult_Unsigned(4, true, 5); Test_ReportResult_Long(5, true, 6); Test_ReportResult_Unsigned_Long(6, true, 7);}

Commands sent from the microcontroller to send message to the Test Panel on Program Visualizer aredisplayed in the Serial Monitor as shown in Figure 5-14.



Figure 5-14. Test Report from Serial Monitor

Test Report is displayed in Test Panel on Program Visualizer as shown in Figure 5-15.Figure 5-15. Test Panel on Program Visualizer

5.10 CheckParameterThe CheckParameter function compares the actual parameter value and the expected parameter value.

void CheckParameter(long lActual, long lExpected) { printf("Expected: %ld, got: %ld => ", lExpected, lActual); if (lActual == lExpected) { printf("ok\n"); } else { printf("wrong!!\n"); }}

5.11 TestValueParsingThe TestValueParsing function is used for debugging to make sure parsing works as expected.

void TestValueParsing() { printf("\n\n--- Test Parsing Values ---\n"); char achBuffer[20]; TParameters Param; Param.m_pchNextParameter = achBuffer;

printf("\n\n--- Value Parsing Test ---\n");

strcpy(achBuffer, "1"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsInteger(&Param, 0), 1);

strcpy(achBuffer, "12");



Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsInteger(&Param, 0), 12);

strcpy(achBuffer, "1234"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsInteger(&Param, 0), 1234);

strcpy(achBuffer, "1234 456"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsInteger(&Param, 0), 1234); CheckParameter(CH_NextParameterAsInteger(&Param, 0), 456);

strcpy(achBuffer, "1003"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsLong(&Param, 0), 1003);

strcpy(achBuffer, "1004"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsUnsignedInteger(&Param, 0), 1004);

strcpy(achBuffer, "1005"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParameterAsUnsignedLong(&Param, 0), 1005);

#ifndef __XC8 //Tried #if ULLONG_MAX>=4294967296 but it doesn't seem to work // XC8 does not support long long types strcpy(achBuffer, "1006"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParametersAsLongLong(&Param, 0), 1006);

strcpy(achBuffer, "1007"); Param.m_pchNextParameter = achBuffer; CheckParameter(CH_NextParametersAsUnsignedLongLong(&Param, 0), 1007); #endif

strcpy(achBuffer, "10.8"); Param.m_pchNextParameter = achBuffer; double dValue = CH_NextParameterAsDouble(&Param, 0); if (abs(dValue - 10.8) < 0.01) { printf("Double conversion ok\n"); } else { printf("Double conversion BAD!!\n"); }}

5.12 Cmd_SetCmd_Set function is called when the SET command is sent.

void Cmd_Set(TParameters *p) { int nA = CH_NextParameterAsInteger(p, -1); //-1 if no valid parameter found int nB = CH_NextParameterAsInteger(p, -1); printf("\nSet A to %d", nA); printf("\nSet B to %d", nB);}

5.13 UpdateUpdate function is called whenever the MLP_Refresh function is called.

void Update(void){ //Core Megunolink Functionality. //Each line tests a different visualiser (i.e. Time plot) TestTableFunctions(); //Table Visualiser https://



www.megunolink.com/documentation/table/ TestTimePlotFunctions(); //Time Plot Visualiser https://www.megunolink.com/documentation/plotting/time-plot/ TestXYPlotFunctions(); //XY Plot Visualiser https://www.megunolink.com/documentation/plotting/xy-plot/ TestMessageMonitor(); //Message Monitor Visualiser https://www.megunolink.com/documentation/serial-monitors/message-monitor-visualizer/ TestInterfacePanel(); //Interface Panel Visualiser https://www.megunolink.com/documentation/interface-panel TestMap(); //Mapping Visualiser https://www.megunolink.com/documentation/mapping/ TestTestReport(); //Test Report on the Programming Visualiser https://www.megunolink.com/documentation/program-device/test-monitor-panel/ //Debugging //These test out parts of the library to make sure parsing and printing works as expected TestPrintFunctions(); TestValueParsing();}

5.14 MLP_ExampleThe MLP_Example function, when called, initializes and sends test messages to the MegunoLink andresponds accordingly.

/* Main application*/void MLP_Example(void) { printf("MegunoLink C Library - Test Program\r\n");

// MegunoLink Command Handler struct CommandHandlerContext Context; CH_Init(&Context); //Initialise Command Handler CH_AddCommand(&Context, "Set", Cmd_Set); //Add "Set" as a command

// Setting MLP Update MLPUpdate_Initialize(); MLP_SetUpdate(Update);

while (1) { CH_Process(&Context); //Process serial stream to match commands

// These test functions will be called every 30 seconds demonstrating functionality in MegunoLink MLP_Refresh(); }}



6. Revision HistoryRevision Description Date

A Initial release 1/2019

MegunoLink Library User's GuideRevision History


The Microchip Web Site

Microchip provides online support via our web site at http://www.microchip.com/. This web site is used asa means to make files and information easily available to customers. Accessible by using your favoriteInternet browser, the web site contains the following information:

• Product Support – Data sheets and errata, application notes and sample programs, designresources, user’s guides and hardware support documents, latest software releases and archivedsoftware

• General Technical Support – Frequently Asked Questions (FAQ), technical support requests, onlinediscussion groups, Microchip consultant program member listing

• Business of Microchip – Product selector and ordering guides, latest Microchip press releases,listing of seminars and events, listings of Microchip sales offices, distributors and factoryrepresentatives

Customer Change Notification Service

Microchip’s customer notification service helps keep customers current on Microchip products.Subscribers will receive e-mail notification whenever there are changes, updates, revisions or erratarelated to a specified product family or development tool of interest.

To register, access the Microchip web site at http://www.microchip.com/. Under “Support”, click on“Customer Change Notification” and follow the registration instructions.

Customer Support

Users of Microchip products can receive assistance through several channels:

• Distributor or Representative• Local Sales Office• Field Application Engineer (FAE)• Technical Support

Customers should contact their distributor, representative or Field Application Engineer (FAE) for support.Local sales offices are also available to help customers. A listing of sales offices and locations is includedin the back of this document.

Technical support is available through the web site at: http://www.microchip.com/support

Microchip Devices Code Protection Feature

Note the following details of the code protection feature on Microchip devices:

• Microchip products meet the specification contained in their particular Microchip Data Sheet.• Microchip believes that its family of products is one of the most secure families of its kind on the

market today, when used in the intended manner and under normal conditions.• There are dishonest and possibly illegal methods used to breach the code protection feature. All of

these methods, to our knowledge, require using the Microchip products in a manner outside theoperating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so isengaged in theft of intellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.



http://www.microchip.com/http://www.microchip.com/http://www.microchip.com/support

• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of theircode. Code protection does not mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving thecode protection features of our products. Attempts to break Microchip’s code protection feature may be aviolation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your softwareor other copyrighted work, you may have a right to sue for relief under that Act.

Legal Notice

Information contained in this publication regarding device applications and the like is provided only foryour convenience and may be superseded by updates. It is your responsibility to ensure that yourapplication meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORYOR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITSCONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE.Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in lifesupport and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend,indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resultingfrom such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectualproperty rights unless otherwise stated.

Trademarks

The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BitCloud,chipKIT, chipKIT logo, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq,Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB,OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, SAM-BA, SpyNIC, SST,SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip TechnologyIncorporated in the U.S.A. and other countries.

ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLightLoad, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of MicrochipTechnology Incorporated in the U.S.A.

Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom,CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dsPICDEM,dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming,ICSP, INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, memBrain, Mindi, MiWi,motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, OmniscientCode Generation, PICDEM, PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE,Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, TotalEndurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA aretrademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.

Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.

GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary ofMicrochip Technology Inc., in other countries.

All other trademarks mentioned herein are property of their respective companies.



© 2018, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.

ISBN: 978-1-5224-4038-3

Quality Management System Certified by DNV

ISO/TS 16949Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and waferfabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in Californiaand India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC®

DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory andanalog products. In addition, Microchip’s quality system for the design and manufacture of developmentsystems is ISO 9001:2000 certified.



AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPECorporate Office2355 West Chandler Blvd.Chandler, AZ 85224-6199Tel: 480-792-7200Fax: 480-792-7277Technical Support:http://www.microchip.com/supportWeb Address:www.microchip.comAtlantaDuluth, GATel: 678-957-9614Fax: 678-957-1455Austin, TXTel: 512-257-3370BostonWestborough, MATel: 774-760-0087Fax: 774-760-0088ChicagoItasca, ILTel: 630-285-0071Fax: 630-285-0075DallasAddison, TXTel: 972-818-7423Fax: 972-818-2924DetroitNovi, MITel: 248-848-4000Houston, TXTel: 281-894-5983IndianapolisNoblesville, INTel: 317-773-8323Fax: 317-773-5453Tel: 317-536-2380Los AngelesMission Viejo, CATel: 949-462-9523Fax: 949-462-9608Tel: 951-273-7800Raleigh, NCTel: 919-844-7510New York, NYTel: 631-435-6000San Jose, CATel: 408-735-9110Tel: 408-436-4270Canada - TorontoTel: 905-695-1980Fax: 905-695-2078

Australia - SydneyTel: 61-2-9868-6733China - BeijingTel: 86-10-8569-7000China - ChengduTel: 86-28-8665-5511China - ChongqingTel: 86-23-8980-9588China - DongguanTel: 86-769-8702-9880China - GuangzhouTel: 86-20-8755-8029China - HangzhouTel: 86-571-8792-8115China - Hong Kong SARTel: 852-2943-5100China - NanjingTel: 86-25-8473-2460China - QingdaoTel: 86-532-8502-7355China - ShanghaiTel: 86-21-3326-8000China - ShenyangTel: 86-24-2334-2829China - ShenzhenTel: 86-755-8864-2200China - SuzhouTel: 86-186-6233-1526China - WuhanTel: 86-27-5980-5300China - XianTel: 86-29-8833-7252China - XiamenTel: 86-592-2388138China - ZhuhaiTel: 86-756-3210040

India - BangaloreTel: 91-80-3090-4444India - New DelhiTel: 91-11-4160-8631India - PuneTel: 91-20-4121-0141Japan - OsakaTel: 81-6-6152-7160Japan - TokyoTel: 81-3-6880- 3770Korea - DaeguTel: 82-53-744-4301Korea - SeoulTel: 82-2-554-7200Malaysia - Kuala LumpurTel: 60-3-7651-7906Malaysia - PenangTel: 60-4-227-8870Philippines - ManilaTel: 63-2-634-9065SingaporeTel: 65-6334-8870Taiwan - Hsin ChuTel: 886-3-577-8366Taiwan - KaohsiungTel: 886-7-213-7830Taiwan - TaipeiTel: 886-2-2508-8600Thailand - BangkokTel: 66-2-694-1351Vietnam - Ho Chi MinhTel: 84-28-5448-2100

Austria - WelsTel: 43-7242-2244-39Fax: 43-7242-2244-393Denmark - CopenhagenTel: 45-4450-2828Fax: 45-4485-2829Finland - EspooTel: 358-9-4520-820France - ParisTel: 33-1-69-53-63-20Fax: 33-1-69-30-90-79Germany - GarchingTel: 49-8931-9700Germany - HaanTel: 49-2129-3766400Germany - HeilbronnTel: 49-7131-67-3636Germany - KarlsruheTel: 49-721-625370Germany - MunichTel: 49-89-627-144-0Fax: 49-89-627-144-44Germany - RosenheimTel: 49-8031-354-560Israel - Ra’ananaTel: 972-9-744-7705Italy - MilanTel: 39-0331-742611Fax: 39-0331-466781Italy - PadovaTel: 39-049-7625286Netherlands - DrunenTel: 31-416-690399Fax: 31-416-690340Norway - TrondheimTel: 47-72884388Poland - WarsawTel: 48-22-3325737Romania - BucharestTel: 40-21-407-87-50Spain - MadridTel: 34-91-708-08-90Fax: 34-91-708-08-91Sweden - GothenbergTel: 46-31-704-60-40Sweden - StockholmTel: 46-8-5090-4654UK - WokinghamTel: 44-118-921-5800Fax: 44-118-921-5820

Worldwide Sales and Service


PrefaceOverviewTable of Contents1. MLP Library Module1.1. Installing MLP Library1.2. MLP Library1.2.1. Communication Interface1.2.2. UART Settings1.2.3. Timer Settings1.2.4. MegunoLink Visualizers1.2.5. Example

2. MLP Library Module API2.1. Command Handler2.2. Command Parameters2.3. Interface Panel2.4. Map2.5. Message Monitor2.6. Table2.7. Test Report2.8. Time Plot2.9. X-Y Plot2.10. MLP Update

3. Quick Setup for MegunoLink Library Project4. MegunoLink Setup4.1. Setting Up Visualizers4.2. Connecting the Device with MegunoLink

5. MLP Example5.1. Included Files5.2. TestPrintFunctions5.3. TestTableFunctions5.4. TestTimePlotFunctions5.5. TestXYPlotFunctions5.6. TestMessageMonitor5.7. TestInterfacePanel5.8. TestMap5.9. TestTestReport5.10. CheckParameter5.11. TestValueParsing5.12. Cmd_Set5.13. Update5.14. MLP_Example

6. Revision HistoryThe Microchip Web SiteCustomer Change Notification ServiceCustomer SupportMicrochip Devices Code Protection FeatureLegal NoticeTrademarksQuality Management System Certified by DNVWorldwide Sales and Service