nem4_rs232_api.c File Reference

Application programming interface for control of Nemesys via RS232. More...

#include "csi_types.h"
#include <math.h>
#include "nem4_rs232_api.h"
#include <stdio.h>

Include dependency graph for nem4_rs232_api.c:

Data Structures

struct  TwoPointScaling

The two points for a two point scaling. More...

Macros

#define CWBIT_FAULT_RESET   0x0080

controlword bit fault reset

#define CWBIT_HALT   0x0100

controlword bit halt

#define CWBIT_HOMING_START   0x0010

controlword bit start homing move

#define CWBIT_IMMEDIATELY   0x0020

change set immediately

#define CWBIT_NEW_SET_POINT   0x0010

new set point

#define CWBIT_OP_EN   0x0008

controlword bit operation enabled

#define CWBIT_QUICK_STOP   0x0004

controlword bit quick stop

#define CWBIT_RELATIVE   0x0040

target position is an relative value

#define CWBIT_SWON   0x0001

controlword bit switch on

#define CWBIT_VOLT_EN   0x0002

controlword bit voltage enabled

#define DRV_PROC_TIME   10

processing time

#define STATE_IS_FAULT(_wState_)   (((_wState_) & 0x004F) == SW_FAULT)

Checks if state is fault.

#define STATE_IS_FAULT_REAC(_wState_)   (((_wState_) & 0x004F) == SW_FAULT_REAC)

Checks if state is fault reaction active.

#define STATE_IS_OP_EN(_wState_)   (((_wState_) & 0x006F) == SW_OP_EN)

Checks if state is operation enabled.

#define STATE_IS_QUICK_STOP(_wState_)   (((_wState_) & 0x006F) == SW_QUICK_STOP)

Checks if state is quick stop.

#define STATE_IS_SWON(_wState_)   (((_wState_) & 0x006F) == SW_SWON)

Checks if state is switch on.

#define STATE_IS_SWON_DIS(_wState_)   (((_wState_) & 0x004F) == SW_SWON_DIS)

Checks if state is disabled.

#define STATE_IS_SWON_NOT_RDY(_wState_)   (((_wState_) & 0x004F) == SW_SWON_NOT_RDY)

Checks if state is not ready to witch on.

#define STATE_IS_SWON_RDY(_wState_)   (((_wState_) & 0x006F) == SW_SWON_RDY)

Checks if state is ready to switch on.

#define SWBIT_FAULT   0x0008

fault

#define SWBIT_INT_LIM   0x0800

internal limit active

#define SWBIT_OP_EN   0x0004

operation enabled

#define SWBIT_QUICK_STOP   0x0020

quick stop

#define SWBIT_REMOTE   0x0200

remote

#define SWBIT_SWON   0x0002

switched on

#define SWBIT_SWON_DIS   0x0040

switch on disabled

#define SWBIT_SWON_RDY   0x0001

ready to switch on

#define SWBIT_TARG_REACHED   0x0400

target reached

#define SWBIT_VOLT_EN   0x0010

voltage enabled

#define SWBIT_WARNING   0x0080

warning

Typedefs

typedef enum eCtrlWord TCtrlWord

Control words of object dictionary entry OD_H6040_CTRL_WORD.

typedef enum eDigOutPurpose TDigOutPurpose

EPOS sepecific purpose of digital outputs

typedef enum eErrHistSub TErrHistSub

Error history sub indexes.

typedef enum eNemObjDicEntries TNemObjDicEntries

Object dictionary entries.

typedef enum eNemOpModes TNemOpModes

Enumeration of Nemesys deviceoperation modes.

typedef struct TwoPointScaling TNemTwoPointScaling

The two points for a two point scaling.

typedef enum eStatusWord TStatusWord

Status words of object dictionary entry OD_H6041_STATUS_WORD.

Enumerations

enum  eCtrlWord {   CW_SHUTDOWN = 0x06, CW_SWON = 0x07, CW_VOLT_DIS = 0x00, CW_QUICK_STOP = 0x02,   CW_OP_DIS = 0x07, CW_OP_EN = 0x0F, CW_FAULT_RST = 0x80, CW_UNDEFINED = 0xFF,   CW_SHUTDOWN = 0x06, CW_SWON = 0x07, CW_VOLT_DIS = 0x00, CW_QUICK_STOP = 0x02,   CW_OP_DIS = 0x07, CW_OP_EN = 0x0F, CW_FAULT_RST = 0x80, CW_UNDEFINED = 0xFF }

Control words of object dictionary entry OD_H6040_CTRL_WORD. More...

enum  eDigOutPurpose {   DIG_OUT_GENERAL_PURPOSE_A = 0x010000, DIG_OUT_GENERAL_PURPOSE_B = 0x100000, DIG_OUT_GENERAL_PURPOSE_A = 0x8000, DIG_OUT_GENERAL_PURPOSE_B = 0x4000,   DIG_OUT_GENERAL_PURPOSE_C = 0x2000, DIG_OUT_GENERAL_PURPOSE_D = 0x1000 }

EPOS sepecific purpose of digital outputs

enum  eErrHistSub { H1003_SUB_01_NUMBER_OF_ERR = 0, H1003_SUB_01_ERR_IDX_1 = 1, H1003_SUB_01_NUMBER_OF_ERR = 0, H1003_SUB_01_ERR_IDX_1 = 1 }

Error history sub indexes.

enum  eNemObjDicEntries {   NemV4_OD_H1003_ERROR_HISTORY = 0x1003, NemV4_OD_H210C_CUSTOM_PERSISTENT_MEM = 0x210C, NemV4_OD_H3000_AXIS_CONFIGURATION = 0x3000, NemV4_OD_H3003_GEAR_CONFIGURATION = 0x3003,   NemV4_OD_H3141_DIG_INPUTS_PROPERTIES = 0x3141, NemV4_OD_H3160_ANALOG_INPUT = 0x3160, NemV4_OD_H3182_ANALOG_OUT = 0x3182, NemV4_OD_H6040_CTRL_WORD = 0x6040,   NemV4_OD_H6041_STATUS_WORD = 0x6041, NemV4_OD_H6060_OP_MODE = 0x6060, NemV4_OD_H6064_ACTUAL_POSITION = 0x6064, NemV4_OD_H606B_VELOCITY_DEMAND = 0x606B,   NemV4_OD_H607A_TARGET_POSITION = 0x607A, NemV4_OD_H607D_SW_POS_LIMITS = 0x607D, NemV4_OD_H607F_PROFILE_VELOCITY_MAX = 0x607F, NemV4_OD_H6081_PROFILE_VELOCITY = 0x6081,   NemV4_OD_H60A9_SI_UNIT_VELOCITY = 0x60A9, NemV4_OD_H60AA_SI_UNIT_ACCELERATION = 0x60AA, NemV4_OD_H60FD_DIGITAL_INPUTS = 0x60FD, NemV4_OD_H60FE_DIG_OUT = 0x60FE,   NEM_OD_H1003_ERROR_HISTORY = 0x1003, NEM_OD_H200C_CUSTOM_PERSISTENT_MEM = 0x200C, NEM_OD_H2078_DIGITAL_OUT_FUNC = 0x2078, NEM_OD_H2081_HOME_POSITION = 0x2081,   NEM_OD_H6040_CTRL_WORD = 0x6040, NEM_OD_H6041_STATUS_WORD = 0x6041, NEM_OD_H6060_OP_MODE = 0x6060, NEM_OD_H6064_ACTUAL_POSITION = 0x6064,   NEM_OD_H606B_VELOCITY_DEMAND = 0x606B, NEM_OD_H607A_TARGET_POSITION = 0x607A, NEM_OD_H607C_HOME_OFFSET = 0x607C, NEM_OD_H6081_PROFILE_VELOCITY = 0x6081,   NEM_OD_H6098_HOMING_METHOD = 0x6098, NEM_OD_H6099_HOMING_SPEEDS = 0x6099 }

Object dictionary entries.

enum  eNemOpModes { NemV4_OP_MODE_PROFILE_POSITION = 1, NemV4_OP_MODE_HOMING = 6, NEM_OP_MODE_PROFILE_POSITION = 1, NEM_OP_MODE_HOMING = 6 }

Enumeration of Nemesys deviceoperation modes. More...

enum  eStatusWord {   SW_SWON_NOT_RDY = 0x00, SW_SWON_DIS = 0x40, SW_SWON_RDY = 0x21, SW_SWON = 0x23,   SW_OP_EN = 0x27, SW_QUICK_STOP = 0x07, SW_FAULT_REAC = 0x0F, SW_FAULT = 0x08,   SW_UNDEFINED = 0xFF, SW_SWON_NOT_RDY = 0x00, SW_SWON_DIS = 0x40, SW_SWON_RDY = 0x21,   SW_SWON = 0x23, SW_OP_EN = 0x27, SW_QUICK_STOP = 0x07, SW_FAULT_REAC = 0x0F,   SW_FAULT = 0x08, SW_UNDEFINED = 0xFF }

Status words of object dictionary entry OD_H6041_STATUS_WORD. More...

Functions

static long NemV4_ClearErrHist (TNemesysV4 *Nemesys)

Clears the device error history and error register. More...

static long NemV4_ExecDrvStateCmd (TNemesysV4 *Nemesys, uint16_t wCmd, uint16_t *pwState, uint16_t wProcessTime)

Execute one single drive state command. More...

static long NemV4_InitDigOutShadowRegister (TNemesysV4 *Nemesys)

static long NemV4_InitForceScalingParam (TNemesysV4 *Nemesys)

static long NemV4_IsState (TNemesysV4 *Nemesys, uint16_t wMask, uint16_t wState, uint8_t *pResult)

Test the status word for a certain bit pattern. More...

static long NemV4_SetControlWord (TNemesysV4 *Nemesys, uint16_t wControlWord)

Transmits the controlword to the device. More...

static long NemV4_SetOpMode (TNemesysV4 *Nemesys, TNemOpModes OpMode)

Change operation mode of Nemesys device. More...

long NemV4ClearFault (TNemesysV4 *Nemesys)

Clear fault state of Nemesys. More...

double NemV4DevicePosToMicrolitres (TNemesysV4 *Nemesys, int32_t Pos)

Converts a device position in inc. More...

double NemV4DevicePosToMillimetres (TNemesysV4 *Nemesys, int32_t Pos)

Convert device position in increments into position in mm. More...

double NemV4DeviceVelToMicrolitresPerMinute (TNemesysV4 *Nemesys, int32_t Velocity)

Converts a device velocity (likely in mrpm) in a flow rate in ul/min using the configured syringe parameters. More...

double NemV4DeviceVelToMillimetresPerMinute (TNemesysV4 *Nemesys, int32_t Velocity)

Converts a device velocity in device units (likely mrprm) into mm/min. More...

long NemV4DevInit (struct CsiBus *Bus, uint8_t NodeId, TNemesysV4 *Nemesys)

Initialize Nemesys device object with all parameters. More...

long NemV4DoseVolume (TNemesysV4 *Nemesys, double Volume_ul, double Flow_ul_min)

Dose a certain volume with a certain flow rate. More...

long NemV4EnableForceMonitoring (TNemesysV4 *Nemesys, int Enable)

Enable / Disable force monitoring functionality. More...

long NemV4GenerateFlow (TNemesysV4 *Nemesys, double Flow_ul_min)

Generate a constant flow until syringe is empty or full. More...

long NemV4GetCurrentFlow (TNemesysV4 *Nemesys, double *Flow_ul_min)

Returns the current flow in ul / min. More...

long NemV4GetCurrentVelocity (TNemesysV4 *Nemesys, int32_t *Velocity)

Read the actual velocity from the Nemesys. More...

long NemV4GetLastDevErr (TNemesysV4 *Nemesys, int32_t *pLastDevErr)

Read last Nemesys error from error register. More...

long NemV4GetMaxFlow (TNemesysV4 *Nemesys, double *Flow_ul_min)

Returns the maximum flow in ul / min. More...

long NemV4GetMaxSyringeLevel (TNemesysV4 *Nemesys, double *Level_ul)

Returns the maximum syringe level in µl. More...

long NemV4GetPosIs (TNemesysV4 *Nemesys, int32_t *PosIs)

Reads the actual position from the Nemesys. More...

long NemV4GetSyringeLevel (TNemesysV4 *Nemesys, double *Level_ul)

Returns the current syringe level in µl. More...

uint32_t NemV4IsEnabled (TNemesysV4 *Nemesys)

Check if Nemesys is in enabled state. More...

uint32_t NemV4IsInFaultState (TNemesysV4 *Nemesys)

Query fault state of Nemesys pump drive. More...

long NemV4IsSafetyStopActive (TNemesysV4 *Nemesys)

Reads the safety stop input. More...

long NemV4IsStopped (TNemesysV4 *Nemesys)

Checks if a dosing unit is moving or stopped. More...

int32_t NemV4MicrolitresPerMinuteToDeviceVel (TNemesysV4 *Nemesys, double ul_min)

Converts a flow rate in ul/min into a device velocity (likely in mrpm). More...

int32_t NemV4MicrolitresToDevicePos (TNemesysV4 *Nemesys, double ul)

Converts a volume in microliters into a device position in increments using the configred syronge parameters. More...

int32_t NemV4MillimetresPerMinuteToDeviceVel (TNemesysV4 *Nemesys, double mm_min)

Converts a velocity in mm/min into a device velocity (likely mrpm). More...

int32_t NemV4MillimetresToDevicePos (TNemesysV4 *Nemesys, double mm)

Converts a position in mm into a device position in inc. More...

long NemV4MoveDistance (TNemesysV4 *Nemesys, int32_t Distance, uint32_t Velocity)

Moves the pusher a certain distance from the current position. More...

long NemV4MoveToPos (TNemesysV4 *Nemesys, int32_t dwPosAbs, uint32_t dwVelocity)

Move pusher to a certain position. More...

long NemV4MoveWithVelocity (TNemesysV4 *Nemesys, int32_t Velocity)

Moves the syringe pusher with the given velocity. More...

long NemV4ReadAnalogInput (TNemesysV4 *Nemesys, enum eNemV4AnalogInput Input, int16_t *Value_mV)

Reads the analog input value of the given Input and returns it in Value_mV. More...

long NemV4ReadDigitalInput (TNemesysV4 *Nemesys, enum eNemV4DigitalInput Input)

Reads the state of one single digital input. More...

long NemV4ReadDigitalInputs (TNemesysV4 *Nemesys, uint32_t *Inputs)

Reads all 4 digital inputs from the device and returns the inputs bitmask in Inputs. More...

long NemV4ReadForceSensor (TNemesysV4 *Nemesys, float *Force_kN)

Reads the internal force sensor value scaled to kN. More...

long NemV4ReadStatusWord (TNemesysV4 *Nemesys, uint16_t *pwStatusWord)

Read status word from Nemesys. More...

long NemV4SetEnabled (TNemesysV4 *Nemesys)

Set single dosing unit into enable state. More...

void NemV4SetSyringe (TNemesysV4 *Nemesys, double InnerSyringeDiameter_mm)

Configure the syringe that is used for flow and volume unit conversion. More...

long NemV4SetSyringeLevel (TNemesysV4 *Nemesys, double Level_ul, double Flow_ul_min)

Set syringe to a certain fill level. More...

long NemV4Stop (TNemesysV4 *Nemesys)

Stops the current dosing move. More...

long NemV4SwitchValve (TNemesysV4 *Nemesys, uint8_t ValvePosition)

Switches a valve connected to the Nemesys I/O connector to a given position. More...

long NemV4WriteDigitalOutput (TNemesysV4 *Nemesys, enum eNemV4DigitalOutput Output, uint8_t On)

Switches one single digital output channel on/off. More...

long NemV4WriteDigitalOutputs (TNemesysV4 *Nemesys, uint32_t OutputMask, uint32_t States)

Switches the given digital outputs on/off. More...

long NemV4WriteForceLimit (TNemesysV4 *Nemesys, float ForceLimit_kN)

Sets a custom force limit. More...

Detailed Description

Application programming interface for control of Nemesys via RS232.

Author

Uwe Kindler (UK)

Date

2019/03/12

Enumeration Type Documentation

enum eCtrlWord

Control words of object dictionary entry OD_H6040_CTRL_WORD.

Enumerator
CW_SHUTDOWN	shutdown drive
CW_SWON	switch on
CW_VOLT_DIS	disable voltage
CW_QUICK_STOP	perform quick stop
CW_OP_DIS	disable operation
CW_OP_EN	set device operational
CW_FAULT_RST	reset device from fault state
CW_SHUTDOWN	shutdown drive
CW_SWON	switch on
CW_VOLT_DIS	disable voltage
CW_QUICK_STOP	perform quick stop
CW_OP_DIS	disable operation
CW_OP_EN	set device operational
CW_FAULT_RST	reset device from fault state

{
    CW_SHUTDOWN    = 0x06, ///< shutdown drive
    CW_SWON        = 0x07, ///< switch on
    CW_VOLT_DIS    = 0x00, ///< disable voltage
    CW_QUICK_STOP  = 0x02, ///< perform quick stop
    CW_OP_DIS      = 0x07, ///< disable operation
    CW_OP_EN       = 0x0F, ///< set device operational
    CW_FAULT_RST   = 0x80, ///< reset device from fault state
    CW_UNDEFINED   = 0xFF
} TCtrlWord;

enum eNemOpModes

Enumeration of Nemesys deviceoperation modes.

Enumerator
NemV4_OP_MODE_PROFILE_POSITION	profile psoition mode - required for any dosing task
NemV4_OP_MODE_HOMING	homing mode - required for calibration and position counter stting
NEM_OP_MODE_PROFILE_POSITION	profile psoition mode - required for any dosing task
NEM_OP_MODE_HOMING	homing mode - required for calibration and position counter stting

{
    NemV4_OP_MODE_PROFILE_POSITION = 1, ///< profile psoition mode - required for any dosing task
    NemV4_OP_MODE_HOMING           = 6, ///< homing mode - required for calibration and position counter stting
} TNemOpModes;

enum eStatusWord

Status words of object dictionary entry OD_H6041_STATUS_WORD.

Enumerator
SW_SWON_NOT_RDY	not ready to switch on
SW_SWON_DIS	switch on disabled
SW_SWON_RDY	ready to switch on
SW_SWON	switched on
SW_OP_EN	operation enabled
SW_QUICK_STOP	quick stop active
SW_FAULT_REAC	fault reaction active
SW_FAULT	fault
SW_UNDEFINED	undefined state
SW_SWON_NOT_RDY	not ready to switch on
SW_SWON_DIS	switch on disabled
SW_SWON_RDY	ready to switch on
SW_SWON	switched on
SW_OP_EN	operation enabled
SW_QUICK_STOP	quick stop active
SW_FAULT_REAC	fault reaction active
SW_FAULT	fault
SW_UNDEFINED	undefined state

{
    SW_SWON_NOT_RDY  = 0x00, ///< not ready to switch on
    SW_SWON_DIS      = 0x40, ///< switch on disabled
    SW_SWON_RDY      = 0x21, ///< ready to switch on
    SW_SWON          = 0x23, ///< switched on
    SW_OP_EN         = 0x27, ///< operation enabled
    SW_QUICK_STOP    = 0x07, ///< quick stop active
    SW_FAULT_REAC    = 0x0F, ///< fault reaction active
    SW_FAULT         = 0x08, ///< fault
    SW_UNDEFINED     = 0xFF  ///< undefined state
} TStatusWord;

Function Documentation

static long NemV4_ClearErrHist ( TNemesysV4 *  Nemesys )

static

Clears the device error history and error register.

The device keeps track of the errors that occured with an internal error history. The function NemV4ClerFault() calls this function to clear the error history.

Parameters

[in]

Nemesys

The device to change

Returns

Error code - ERR_NOERR indicates success

Referenced by NemV4ClearFault().

{
    return CsiDevWriteObject(&Nemesys->Device, NemV4_OD_H1003_ERROR_HISTORY,
        H1003_SUB_01_NUMBER_OF_ERR, 0);
}

Here is the call graph for this function:

long NemV4_ExecDrvStateCmd ( TNemesysV4 *  Nemesys, uint16_t  wCmd, uint16_t *  pwState, uint16_t  wProcessTime  )

static

Execute one single drive state command.

The function excutes one drive state command, waits a certain amount of time for the drive to process the command (wProcessTime) and then reads the statusword of the device and returns it to the application.

Parameters

[in]	Nemesys	The device to query
[in]	wCmd	The command to execute
[out]	pwState	State of the devcie after execution of the command in wCmd
[in]	wProcessTime	Time between sending the command and reading the status

Returns

Error code - ERR_NOERR indicates success

Referenced by NemV4SetEnabled().

{
    long Result;

    Result = NemV4_SetControlWord(Nemesys, wCmd);
    if (Result != ERR_NOERR)
    {
        return Result;
    }

    if (wProcessTimeMs)
    {
        CsiSleep(wProcessTimeMs); // give drive some time to process cmd
    }

    return NemV4ReadStatusWord(Nemesys, pwState);
}

Here is the call graph for this function:

static long NemV4_IsState ( TNemesysV4 *  Nemesys, uint16_t  wMask, uint16_t  wState, uint8_t *  pResult  )

static

Test the status word for a certain bit pattern.

The function applies the mask to the status word and checks if the masked statusword matches the bitpattern in state.

Parameters

[in]	Nemesys	The device to query
[in]	wMask	The bitmask to apply to device statusword
[in]	wState	The state bitmask to check
[out]	pResult	Result of the test (0 = false, 1 = true)

Returns

Error code - ERR_NOERR indicates success

Referenced by NemV4IsEnabled(), NemV4IsInFaultState(), and NemV4IsStopped().

{
    long    Result;
    uint16_t StatusWord;

    Result = NemV4ReadStatusWord(Nemesys, &StatusWord);

    if ((StatusWord & wMask) == wState)
    {
        *pResult = 1;
    }
    else
    {
        *pResult = 0;
    }

    return Result;
}

Here is the call graph for this function:

static long NemV4_SetControlWord ( TNemesysV4 *  Nemesys, uint16_t  wControlWord  )

static

Transmits the controlword to the device.

Call this function to change th controlword.

Parameters

[in]	Nemesys	The device to change
[in]	wControlWord	The new controlword to store into device

Returns

Error code - ERR_NOERR indicates success

See also

NemV4Calibrate(), NemV4_SetHomingSpeed(), NemV4_SetHomingMode()

Referenced by NemV4_ExecDrvStateCmd(), NemV4ClearFault(), NemV4MoveToPos(), and NemV4Stop().

{
    uint32_t controlword = wControlWord;
    return CsiDevWriteObject(&Nemesys->Device, NemV4_OD_H6040_CTRL_WORD, 0, controlword);
}

Here is the call graph for this function:

static long NemV4_SetOpMode ( TNemesysV4 *  Nemesys, TNemOpModes  OpMode  )

static

Change operation mode of Nemesys device.

A Nemesys device can operate in two different operation modes. During normal dosing the device works in profile position mode (NEM_OP_MODE_PROFILE_POSITION). During calibration the device is in homing mode (NEM_OP_MODE_HOMING).

Parameters

[in]	Nemesys	The device to change
[in]	OpMode	The new operation mode to set

Returns

Error code - ERR_NOERR indicates success

Referenced by NemV4DevInit(), and NemV4MoveToPos().

{
    long Result;
    uint32_t dwOpMode = OpMode;

    Result = CsiDevWriteObject(&Nemesys->Device, NemV4_OD_H6060_OP_MODE, 0, dwOpMode);
    if (Result != ERR_NOERR)
    {
        return Result;
    }

    Nemesys->OpMode = OpMode; // stroe operation mode in shadow buffer
    return Result;
}

Here is the call graph for this function: