CNC Calc plug-in exported functions

Classes
struct	CNC_CALC_INIT_DATA
	Initialization structure. More...
struct	CNC_CALC_RETURN_VALUE
	Holds changed G-code parts. More...

Typedefs
typedef int32_t	CNC_CALC_LOAD(const CNC_CALC_INIT_DATA *pInitData)
	typedef for CNC_Calc_Load
typedef int32_t	CNC_CALC_UNLOAD()
	typedef for CNC_Calc_Unload
typedef uint32_t	CNC_CALC_GET_STRUCTURES_SIZE(uint32_t structureIdx)
	typedef for CNC_Calc_Get_Structures_Size
typedef int32_t	CNC_CALC_GET_COMPATIBILITY_IDS(uint32_t *pID_COMPATIBILITY, uint32_t *pID_MEMORY_COMPATIBILITY, uint32_t *pID_CNC_COMPATIBILITY)
	typedef for CNC_Calc_Get_Compatibility_IDs
typedef int32_t	CNC_CALC_START(uint32_t intIdx, int32_t regime, const cnc::SIMPLE_GM_PARAMS_WIN32 *pInitPos, CNC_CALC_RETURN_VALUE *pChangedParts)
	typedef for CNC_Calc_Start
typedef int32_t	CNC_CALC_GFUNC(uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pGFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	typedef for CNC_Calc_GFunc
typedef int32_t	CNC_CALC_MFUNC(uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pMFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	typedef for CNC_Calc_MFunc
typedef int32_t	CNC_CALC_FINISH(uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pFinishMFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	typedef for CNC_Calc_Finish

Functions
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_Load (const CNC_CALC_INIT_DATA *pInitData)
	Plug-in DLL initialization. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_Unload ()
	Plug-in DLL cleanup. More...
CNC_CALC_DLL_EXPORT uint32_t	CNC_Calc_Get_Structures_Size (uint32_t structureIdx)
	Check structure sizes - test for compatibility. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_Get_Compatibility_IDs (uint32_t *pID_COMPATIBILITY, uint32_t *pID_MEMORY_COMPATIBILITY, uint32_t *pID_CNC_COMPATIBILITY)
	Returns compatibility numbers at the time of plug-in build. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_Start (uint32_t intIdx, int32_t regime, const cnc::SIMPLE_GM_PARAMS_WIN32 *pInitPos, CNC_CALC_RETURN_VALUE *pChangedParts)
	Called before the G-code execution. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_GFunc (uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pGFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	Called for any G function inside G-code. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_MFunc (uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pMFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	Called for any M function inside G-code. More...
CNC_CALC_DLL_EXPORT int32_t	CNC_Calc_Finish (uint32_t intIdx, const cnc::SIMPLE_GM_PARAMS_WIN32 *pFinishMFunc, CNC_CALC_RETURN_VALUE *pChangedParts)
	Called as the last function of the G-code. More...

Variables
constexpr int32_t	CNC_CALC_MFUNC_OFFSET { 10000 }
constexpr uint32_t	CNC_CALC_DISABLE_AUTOMATIC_GCODEINDEX_UPDATE_BIT { 0x01U }
	if used, TGMotion does not automatically update GCodeIndex value of the inserted parts
constexpr uint32_t	CNC_CALC_MAX_STATIC_RETURNED_PARTS { 8U }
constexpr int32_t	CNC_CALC_RETURN_ERROR { -1 }
constexpr int32_t	CNC_CALC_RETURN_IGNORE { 0 }
constexpr int32_t	CNC_CALC_RETURN_USE { 1 }
constexpr int32_t	CNC_CALC_RETURN_OK { 1 }
constexpr int32_t	CNC_CALC_RETURN_FEED_ONLY { 2 }
constexpr uint32_t	CNC_CALC_IDX_INIT_DATA_STRUCT { 0U }
	parameter for CNC_Calc_Get_Structures_Size
constexpr uint32_t	CNC_CALC_IDX_SIMPLE_GM_PARAMS_BASE_STRUCT { 1U }
	parameter for CNC_Calc_Get_Structures_Size
constexpr uint32_t	CNC_CALC_IDX_RETURN_VALUE_STRUCT { 2U }
	parameter for CNC_Calc_Get_Structures_Size

Detailed Description

The CNC module can use an external PLC-like DLL plug-in for dynamic G-code recalculation. This plug-in DLL must NOT use any external OS libraries, the standard C library must be statically linked. Its functions will be called during G-code execution which allow to change almost any part or insert new parts to G-code flow.
It is not necessary to implement all exported functions, see their detailed description, but some functions are mandatory. There is just one plug-in common for all CNC cores.
Loading of plug-in can be done only during stop CNC statuses (not inside a movement). After load, the status is set to cnc::cnc_status::INVALID_00 and the G-code must be loaded (compile & test (and/or simulation)) again. The same status is set after plug-in unload.
Since changing and inserting new G-code parts leads to different number of total G-code parts of the G-code, also the GCodeIndex (cnc::SIMPLE_GM_PARAMS_WIN32::m_gCodeIndex) values are different. TG Motion automatically handles the number of inserted parts and increments the G-code index value accordingly, so its value is monotonically increasing. However the plug-in can manage the G-code index values itself by setting bit CNC_CALC_DISABLE_AUTOMATIC_GCODEINDEX_UPDATE_BIT (0x01) to returned CNC_CALC_RETURN_VALUE::options value.

Function Documentation

CNC_Calc_Finish()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_Finish	(	uint32_t	intIdx,
		const cnc::SIMPLE_GM_PARAMS_WIN32 *	pFinishMFunc,
		CNC_CALC_RETURN_VALUE *	pChangedParts
	)

Called as the last function of the G-code.

Can be used to flush potential G or M functions accumulated in the plug-in.

Parameters

intIdx	Interpolator number. Value from 0 to (MAX_CORES - 1)
pFinishMFunc	Contains the last G-code position in cnc::SIMPLE_GM_PARAMS_WIN32::m_s field. The cnc::SIMPLE_GM_PARAMS_WIN32::m_func value is set to -30.
pChangedParts	Sequence (or just one) of G-code parts to be sent to the system, if the return value is CNC_CALC_RETURN_USE.

Note

Implementation of this function is optional.

CNC_Calc_Get_Compatibility_IDs()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_Get_Compatibility_IDs	(	uint32_t *	pID_COMPATIBILITY,
		uint32_t *	pID_MEMORY_COMPATIBILITY,
		uint32_t *	pID_CNC_COMPATIBILITY
	)

Returns compatibility numbers at the time of plug-in build.

This function must be implemented. It is necessary for checking the versions of the plug-in and TG Motion.

Parameters

pID_COMPATIBILITY	pointer to variable where the ID_COMPATIBILITY number is returned
pID_MEMORY_COMPATIBILITY	pointer to variable where the ID_MEMORY_COMPATIBILITY number is returned
pID_CNC_COMPATIBILITY	pointer to variable where the ID_CNC_COMPATIBILITY number is returned

Returns

Always 1.

Example

 // The following code can be used to implement this function
CNC_CALC_DLL_EXPORT int32_t TOOLCHAIN_CALLTYPE CNC_Calc_Get_Compatibility_IDs(uint32_t *pID_COMPATIBILITY,
                                                                              uint32_t *pID_MEMORY_COMPATIBILITY,
                                                                              uint32_t *pID_CNC_COMPATIBILITY)
{
  assert(pID_COMPATIBILITY != nullptr);
  assert(pID_MEMORY_COMPATIBILITY != nullptr);
  assert(pID_CNC_COMPATIBILITY != nullptr);
  if (pID_COMPATIBILITY)        *pID_COMPATIBILITY = ID_COMPATIBILITY;
  if (pID_MEMORY_COMPATIBILITY) *pID_MEMORY_COMPATIBILITY = ID_MEMORY_COMPATIBILITY;
  if (pID_CNC_COMPATIBILITY)    *pID_CNC_COMPATIBILITY = ID_CNC_COMPATIBILITY;
  return CNC_CALC_RETURN_OK;
}

CNC_Calc_Get_Structures_Size()

CNC_CALC_DLL_EXPORT uint32_t CNC_Calc_Get_Structures_Size

(

uint32_t

structureIdx

)

Check structure sizes - test for compatibility.

This function must be implemented. It is necessary for checking the versions of the plug-in and TG Motion.

Parameters

structureIdx

Determines which structure size is asked for: Value Description 0 sizeof(CNC_CALC_INIT_DATA) 1 sizeof(cnc::SIMPLE_GM_PARAMS_WIN32) 2 sizeof(CNC_CALC_RETURN_VALUE)

Returns

Structure size in bytes for valid structureIdx or zero.

Example

 // The following code can be used to implement the function.
CNC_CALC_DLL_EXPORT uint32_t TOOLCHAIN_CALLTYPE CNC_Calc_Get_Structures_Size(uint32_t structureIdx)
{
  switch (structureIdx)
  {
  case CNC_CALC_IDX_INIT_DATA_STRUCT:
    return sizeof(CNC_CALC_INIT_DATA);
  case CNC_CALC_IDX_SIMPLE_GM_PARAMS_BASE_STRUCT:
    return sizeof(cnc::SIMPLE_GM_PARAMS_WIN32);
  case CNC_CALC_IDX_RETURN_VALUE_STRUCT:
    return sizeof(CNC_CALC_RETURN_VALUE);
  default:
    break;
  }
  return 0; // size of 0 means error (invalid structureIdx value)
}

CNC_Calc_GFunc()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_GFunc	(	uint32_t	intIdx,
		const cnc::SIMPLE_GM_PARAMS_WIN32 *	pGFunc,
		CNC_CALC_RETURN_VALUE *	pChangedParts
	)

Called for any G function inside G-code.

This function is called for all the G functions (with any number) situated in the G-code text. Usually will be used to modify movement functions like G1, G2, G3, but can be used also to implement special functions ("macros") or machining cycles. If necessary, can also return CNC_CALC_RETURN_USE, but set the number of entries in CNC_CALC_RETURN_VALUE to zero (CNC_CALC_RETURN_VALUE::nEntriesInPart0 = 0, CNC_CALC_RETURN_VALUE::nDynamicEntriesInPart1 = 0). In this case no parts will be sent to system for that original G-code. The plug-in can remember this part and send it in the next call of CNC_Calc_GFunc(), CNC_Calc_MFunc() or CNC_Calc_Finish(). This would allow e.g. to rotate a plasma head between parts.

Parameters

intIdx	Interpolator number. Value from 0 to (MAX_CORES - 1)
pGFunc	The original G function from G-code text.
pChangedParts	Sequence of G-code parts (G or M functions) to be sent to the system, if the return value is CNC_CALC_RETURN_USE or CNC_CALC_RETURN_FEED_ONLY. If the modified function shall be a M function, its number must be set to SIMPLE_GM_PARAMS_WIN32::m_func plus the constant CNC_CALC_MFUNC_OFFSET.

Returns

Value	Description
2	the CNC_CALC_RETURN_VALUE::dblFeed is used to modify original (pGFunc) feed. No other fields of pChangedParts are used.
1	the pChangedParts structure contains valid values
0	no change to original G-code (call is ignored and the original values in pGFunc are used)
-1	error - stops from calling any plug-in function till unload/load of the plug-in.

Example1

 // Simple example: half the feed of the G1 larger than 10 mm
CNC_CALC_DLL_EXPORT int32_t TOOLCHAIN_CALLTYPE CNC_Calc_GFunc(uint32_t intIdx,
                                          const SIMPLE_GM_PARAMS_WIN32 *pGFunc,
                                          CNC_CALC_RETURN_VALUE *pChangedParts)
{
  // get the type of G func
  if (pGFunc->m_func == 1) // G1
  {
    // calculate G1 length from corrected values
    float64_t len = pGFunc->m_calcE.Length(pGFunc->m_calcS);
    if (len > 10.0)
    {
      pChangedParts->dblFeed = pGFunc->m_pars[ADDR_IDX('F')] / 2.0;
      return CNC_CALC_RETURN_FEED_ONLY; // notify the callee we changed the feed only
    }
  }
  UNREFERENCED_PARAM(intIdx);
  return CNC_CALC_RETURN_IGNORE;
}

Example2

// More advanced example: if the G1 is larger than 20 mm, 
// split it to two parts and insert M666 between these two parts.
CNC_CALC_DLL_EXPORT int32_t TOOLCHAIN_CALLTYPE CNC_Calc_GFunc(uint32_t intIdx,
                                          const SIMPLE_GM_PARAMS_WIN32 *pGFunc,
                                          CNC_CALC_RETURN_VALUE *pChangedParts)
{
  // change the G1 to two G1 (both half of the length)
  // insert M666 func between them
  if (pGFunc->m_func == 1) // G1
  {
    // calculate G1 length from corrected values
    float64_t len = pGFunc->m_calcE.Length(pGFunc->m_calcS);
    if (len > 20.0)
    {
      // first copy original G1 to all the three parts and then change only the needed values
      pChangedParts->sParts0[0] = *pGFunc;
      pChangedParts->sParts0[1] = *pGFunc;
      pChangedParts->sParts0[2] = *pGFunc;
 
      // calculate the middle point
      P10DOUBLE middleCalc(pGFunc->m_calcS + ((pGFunc->m_calcE - pGFunc->m_calcS) * 0.5));
      P10DOUBLE middleOrig(pGFunc->m_s     + ((pGFunc->m_e     - pGFunc->m_s)     * 0.5));
 
      // set it to relevant values
      pChangedParts->sParts0[0].m_calcE = middleCalc;
      pChangedParts->sParts0[0].m_e = middleOrig;
 
      pChangedParts->sParts0[1].m_calcS = middleCalc;
      pChangedParts->sParts0[1].m_calcE = middleCalc;
      pChangedParts->sParts0[1].m_s = middleOrig;
      pChangedParts->sParts0[1].m_e = middleOrig;
 
      pChangedParts->sParts0[2].m_calcS = middleCalc;
      pChangedParts->sParts0[2].m_s = middleOrig;
 
      // set the part types
      pChangedParts->sParts0[0].m_func = 1; // G1
      pChangedParts->sParts0[1].m_func = CNC_CALC_MFUNC_OFFSET + 666; // M666
      pChangedParts->sParts0[2].m_func = 1; // G1
 
      // set the number of changed parts
      pChangedParts->nEntriesInPart0 = 3;
      pChangedParts->nDynamicEntriesInPart1 = 0; // dynamic entries not used
 
      return CNC_CALC_RETURN_USE; // notify the callee the pChangedParts contain valid data
    }
  }
 
  UNREFERENCED_PARAM(intIdx);
  return CNC_CALC_RETURN_IGNORE;
}

Note

Implementation of this function is optional.

CNC_Calc_Load()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_Load

(

const CNC_CALC_INIT_DATA *

pInitData

)

Plug-in DLL initialization.

Called after DLL load. Allows to init internal variables. Must be implemented.

Parameters

pInitData

Pointer to initialization structure with shared memory access functions.

Returns

Value	Description
-1	error, do not use the plug-in DLL
any other value	success

CNC_Calc_MFunc()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_MFunc	(	uint32_t	intIdx,
		const cnc::SIMPLE_GM_PARAMS_WIN32 *	pMFunc,
		CNC_CALC_RETURN_VALUE *	pChangedParts
	)

Called for any M function inside G-code.

This function is called for all the M functions (with any number) situated in the G-code text. Can be used to expand special M functions to set of movements and other M functions, already implemented in PLC.

Parameters

intIdx	Interpolator number. Value from 0 to (MAX_CORES - 1)
pMFunc	Original M function description from G-code text.
pChangedParts	Sequence (or just one) of G-code parts to be sent to the system, if the return value is CNC_CALC_RETURN_USE or CNC_CALC_RETURN_FEED_ONLY. If the modified function shall be a M function, its number must be set to cnc::SIMPLE_GM_PARAMS_WIN32::m_func plus the constant CNC_CALC_MFUNC_OFFSET.

Returns

Value	Description
1	the pChangedParts structure contains valid values
0	no change to original G-code (call is ignored and the original values in pMFunc are used)
-1	error - stops from calling any plug-in function till unload/load of the plug-in.

Note

Implementation of this function is optional.

CNC_Calc_Start()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_Start	(	uint32_t	intIdx,
		int32_t	regime,
		const cnc::SIMPLE_GM_PARAMS_WIN32 *	pInitPos,
		CNC_CALC_RETURN_VALUE *	pChangedParts
	)

Called before the G-code execution.

Allow to store initial value, insert special G-code parts at the beginning of G-code execution, etc. Also signals the mode in the regime parameter.

Parameters

intIdx	Interpolator number. Value from 0 to (MAX_CORES - 1).
regime	Actual regime. Regime is kept until call to CNC_Calc_Finish(). Can be: Value Description 10 SIMULATION 20 TEST 30 FORWARD 31 FORWARD_NO_MFUNC 32 BACKWARD 33 FORWARD_SKIP_FIRST_M 40 CONNECT
pInitPos	Initial position is set in cnc::SIMPLE_GM_PARAMS_WIN32::m_s field. cnc::SIMPLE_GM_PARAMS_WIN32::m_planeTool is set to initial plane (G17, G18, G19 or 20 for lathe (ZX)) cnc::SIMPLE_GM_PARAMS_WIN32::m_func is -33.
pChangedParts	G-code parts to be sent to the system, if the return value is CNC_CALC_RETURN_USE.

Returns

Value	Description
1	the pChangedParts structure contains valid values and will be used
0	no change to original G-code (call is ignored)
-1	error - stops from calling any plug-in function till unload/load of the plug-in.

Note

Implementation of this function is optional.

CNC_Calc_Unload()

CNC_CALC_DLL_EXPORT int32_t CNC_Calc_Unload

(

)

Plug-in DLL cleanup.

Called before DLL unload. Can be used for freeing memory etc. Must be implemented.

Returns

Return value is ignored.

Variable Documentation

CNC_CALC_MAX_STATIC_RETURNED_PARTS

constexpr uint32_t CNC_CALC_MAX_STATIC_RETURNED_PARTS { 8U }

constexpr

To speed up G-code parts insertion, up to 8 parts can be inserted just by using statically allocated memory in CNC_CALC_RETURN_VALUE::sParts0 array. If there is a need of more parts to be inserted, dynamically allocated memory must be used and set to the CNC_CALC_RETURN_VALUE::dParts1 pointer.

CNC_CALC_MFUNC_OFFSET

constexpr int32_t CNC_CALC_MFUNC_OFFSET { 10000 }

constexpr

M function number offset to distinguish between G and M functions in cnc::SIMPLE_GM_PARAMS_WIN32::m_func field

CNC_CALC_RETURN_ERROR

constexpr int32_t CNC_CALC_RETURN_ERROR { -1 }

constexpr

For displaying error text, use CNC_CALC_INIT_DATA::pPrintf function. Notify TGMotion of an error inside plug-in.

CNC_CALC_RETURN_FEED_ONLY

constexpr int32_t CNC_CALC_RETURN_FEED_ONLY { 2 }

constexpr

Used by CNC_Calc_Start(), CNC_Calc_GFunc(), CNC_Calc_MFunc(), CNC_Calc_Finish() functions. Only the CNC_CALC_RETURN_VALUE::dblFeed value is used to modify the part feed, all other values are ignored.

CNC_CALC_RETURN_IGNORE

constexpr int32_t CNC_CALC_RETURN_IGNORE { 0 }

constexpr

Used by CNC_Calc_Start(), CNC_Calc_GFunc(), CNC_Calc_MFunc(), CNC_Calc_Finish() functions. The call to the function is ignored and original part is used (no modification).

CNC_CALC_RETURN_OK

constexpr int32_t CNC_CALC_RETURN_OK { 1 }

constexpr

(the same value as CNC_CALC_RETURN_USE) Success value of non-calc funcions.

CNC_CALC_RETURN_USE

constexpr int32_t CNC_CALC_RETURN_USE { 1 }

constexpr

Used by CNC_Calc_Start(), CNC_Calc_GFunc(), CNC_Calc_MFunc(), CNC_Calc_Finish() functions. TG Motion use the values in the CNC_CALC_RETURN_VALUE struct. The original part is not used. If needed, must be copied by the plug-in.