P1AM API Reference

Function:

uint8_t P1.init();

Purpose:
Initializes the P1AM communications to the P1 modules. This function should be called before any other P1 module access functions are called.

Parameters:
None.

Return values:
0 - 15 - Number of P1 modules found connected to P1AM.

Function:

uint32_t P1.readDiscrete(uint8_t slot, uint8_t channel = 0);

Purpose:
Reads back the value(s) for a Discrete Input module. To read back the value for a specific Discrete Input, specify the channel number in the “channel” variable. To read back the integer value for all Discrete Inputs on that module, specify a value of 0 in the “channel” variable.

Parameters:

Return values:
A 32-bit value indicating either a 1 or 0 for the specific point requested or the integer value of all points of the module (when “channel” = 0).

Function:

void P1.writeDiscrete(uint32_t data, uint8_t slot, uint8_t channel = 0);

Purpose:
Writes the value(s) to the Discrete Output modules. To write to a specific point, set the “data” variable to a 0 or 1 and specify a discrete output point value in the “channel” variable. To write to all discrete output points at the same time, specify an integer value in the “data” variable and set the “channel” variable to 0.

Parameters:

Return values:
None.

Function:

int P1.readAnalog(uint8_t slot, uint8_t channel);

Purpose:
Reads back the raw, un-scaled, integer value from an Analog Input Module.

Parameters:

Return values:
A 32-bit value for the specified channel. For 12-bit analog modules, this will be a value between 0 - 4095. For 16-bit analog modules, this will be a value between 0 and 65535 or -32768 and 32767.

Function:

float P1.readTemperature(uint8_t slot, uint8_t channel);

Purpose:
Reads back the raw, un-scaled, floating point value from a Temperature Input Module.

Parameters:

Return values:
A 32-bit floating point value for the specified channel. The value will be in degrees for temperature configurations and millivolts for voltage configurations.

Function:

void P1.writeAnalog(uint32_t data, uint8_t slot, uint8_t channel);

Purpose:
Writes to a single Analog Output channel.

Parameters:

Return values:
None.

Function:

void P1.readBlockData(char *buf, uint16_t len, uint16_t offset, uint8_t type);

Purpose:
This function gives the ability to read from many modules at one time. This is an advanced function that requires calculations of the module data sizes to specify offsets and lengths into the data image of the base controller. This function does not return the values requested but, instead, places them into the “buf” array. The maximum amount of data that can be requested in one read is 1200 bytes. If there is more than 1200 bytes of data in the Base Controller, you will have to offset in to the next block of data in the Base Controller.

Parameters:

Return values:
None.

Function:

void P1.writeBlockData(char *buf, uint16_t len, uint16_t offset, uint8_t type);

Purpose:
This function gives the ability to write to many modules at one time. This is an advanced function that requires calculations of the module data sizes to specify offsets and lengths into the data image of the base controller. The maximum amount of data that can be requested in one write is 1200 bytes. If there is more than 1200 bytes of data in the Base Controller, you will have to offset in to the next block of data in the Base Controller.

Parameters:

Return values:
None.

Function:

void P1.writePWM(float duty, uint32_t freq, uint8_t slot, uint8_t channel);

Purpose:
This function controls the P1-04PWM Pulse Width Modulation module. The duty and frequency can be set for each channel.

Parameters:

Return values:
None.

Function:

void P1.writePWMDuty(float duty, uint8_t slot, uint8_t channel);

Purpose:
This function allows the duty cycle to be changed on the P1-04PWM module while running at the current frequency. To change both the duty and the frequency, use the P1.writePWM function instead.

Parameters:

Return values:
None.

Function:

void P1.writePWMFreq(uint32_t freq, uint8_t slot, uint8_t channel);

Purpose:
This function allows the frequency to be changed on the P1-04PWM module while running with the current duty cycle. To change both the duty and the frequency, use the P1.writePWM function instead.

Parameters:

Return values:
None.

Function:

void P1.writePWMDir(bool data, uint8_t slot, uint8_t channel);

Purpose:
This function sets a channel configured on a P1-04PWM for DIR to be enabled high or low. This is typically used in conjunction with another channel set for PWM wired to a Stepper Motor controller for direction change.

Parameters:

Return values:
None.

Function:

uint8_t P1.printModules();

Purpose:
This function prints out in the serial monitor, the P1 modules discovered by the P1AM.

Parameters:
None.

Return values:
An integer value displaying the number of modules found is returned by the function.

Function:

uint8_t P1.checkUnderRange(uint8_t slot, uint8_t channel = 0);

Purpose:
This function returns the Under-Range status from an Analog Input module. The status for a specific channel can be request or the status byte for the entire module can be requested (channel = 0). Consult the individual module documentation to see if it supports this status item.

Parameters:

Return values:
An 8-bit integer value is returned. The value will be 0 or 1 for specific channel requests. If the entire module status is requested (channel = 0), each bit of the byte will correspond to the under-range status for that channel (LSB - Channel 1).

Function:

uint8_t P1.checkOverRange(uint8_t slot, uint8_t channel = 0);

Purpose:
This function returns the Over-Range status from an Analog Input module. The status for a specific channel can be request or the status byte for the entire module can be requested (channel = 0). Consult the individual module documentation to see if it supports this status item.

Parameters:

Return values:
An 8-bit integer value is returned. The value will be 0 or 1 for specific channel requests. If the entire module status is requested (channel = 0), each bit of the byte will correspond to the over-range status for that channel (LSB - Channel 1).

Function:

uint8_t P1.checkBurnout(uint8_t slot, uint8_t channel = 0);

Purpose:
This function returns the Burnout status from an Analog Input module. The status for a specific channel can be request or the status byte for the entire module can be requested (channel = 0). Consult the individual module documentation to see if it supports this status item.

Parameters:

Return values:
An 8-bit integer value is returned. The value will be 0 or 1 for specific channel requests. If the entire module status is requested (channel = 0), each bit of the byte will correspond to the Burnout status for that channel (LSB - Channel 1).

Function:

uint8_t P1.check24V(uint8_t slot);

Purpose:
This function returns the 24 VDC status from a module. Consult the individual module documentation to see if it supports this status item.

Parameters:

Return values:
An 8-bit integer value is returned. The value will be 0 if 24 VDC is present or 1 if 24 VDC is missing.

Function:

char P1.readStatus(int byteNum, int slot);

Purpose:
This function returns a single status byte from a specific module.

Parameters:

Return values:
The status byte value is returned as a char.

Function:

void P1.readStatus(char buf[], uint8_t slot);

Purpose:
This function returns all status byte values from a specific module. The data is not returned from the function but stored in the “buf” array.

Parameters:

Return values:
None.

Function:

bool P1.configureModule(char cfgData[], uint8_t slot);

Purpose:
This function allows you to configure the settings of the P1 modules. Each module may have a different configuration so consult the individual module documentation for detailed breakdown of this data. This function would be more typically used for applications that have dynamic configuration data. For more static configuration setups, use the next function (overload function) that has a constant char array defined.

Parameters:

Return values:
A Boolean value of 1 is returned for a successful configuration change.

Function:

bool P1.configureModule(const char cfgData[], uint8_t slot);

Purpose:
This function allows you to configure the settings of the P1 modules. Each module may have a different configuration so consult the individual module documentation for detailed breakdown of this data. 

Parameters:

Return values:
A Boolean value of 1 is returned for a successful configuration change.

Function:

void P1.readModuleConfig(char cfgData[], uint8_t slot);

Purpose:
This function allows you to read the current configuration of the specified module. Each module may have a different configuration so consult the individual module documentation for detailed breakdown of this data. 

Parameters:

Return values:
None.

Function:

void P1.configWD(uint16_t milliseconds, uint8_t toggle);

Purpose:
This function configures the watchdog timer value in milliseconds and watchdog behavior option, defined by the “toggle” parameter. A value of 1 in the “toggle” parameter will reset the CPU after 5000 milliseconds have passed. A value of 0 will stop the CPU until a power cycle occurs. To use the watchdog, it must be configured first by the “P1.configWD()” function. To start the watchdog, the “P1.startWD()” must be called. If the “P1.petWD()” or a Base Controller function is not called at a faster rate than the time frame specified in the “P1.configWD()” function, the watchdog will occur. To stop the watchdog timer, use the “P1.stopWD()” function.

Parameters:

Return values:
None.

Function:

void P1.startWD();

Purpose:
This function starts the watchdog timer. See the purpose of the “P1.configWD()” function for more details on using the watchdog feature.

Parameters:
None.

Return values:
None.

Function:

void P1.stopWD();

Purpose:
This function stops the watchdog timer. See the purpose of the “P1.configWD()” function for more details on using the watchdog feature.

Parameters:
None.

Return values:
None.

Function:

void P1.petWD();

Purpose:
This function is used to keep the watchdog timer from timing out if P1 I/O functions are not being called often enough. See the purpose of the “P1.configWD()” function for more details on using the watchdog feature.

Parameters:
None.

Return values:
None.

Function:

uint32_t P1.getFwVersion();

Purpose:
This function is used to retrieve the firmware version of the P1 Base Controller. The format of the value returned (in bytes) is X.Y.ZZ.

Parameters:
None.

Return values:
A 32-bit integer is returned for the firmware version.

Function:

bool P1.isBaseActive();

Purpose:
This function checks to see if the P1 Base controller is active. To activate the P1 Base Controller, call the “P1.init()” function.

Parameters:
None.

Return values:
A Boolean value of 1 is returned if the P1 Base controller is active.

Function:

uint8_t P1.checkConnection(uint8_t numberOfModules = 0);

Purpose:
This function checks to see if any of the P1 modules have gone missing. If the “numberOfModules” variable contains a slot value, the function will return either a 0 (if everything is Ok or the value of the first slot number, from the left, that presented a problem. For example: if there are only 3 modules and a value of 4 was placed into the “numberOfModules” variable, the result would be “4”. The same would occur is a value of 5 was placed into the “numberOfModules” variable since slot 3 is the last good slot. If a value of 0 is passed into the “numberOfModules” variable, the function will return the number of modules found in the last init() function. In the example above, the results would be 1, 2, 3, 0 if sending a value of 0 in the “numberOfModules” variable when there are 3 modules.

Parameters:

Return values:
A 8-bit value is returned that either indicates a 0 if the slot number passed to the function is good, the slot number where the problem is found if there is a problem or the number of modules found with the last init() function if a value of 0 is passed into the function. See the Purpose explanation above.

Function:

uint16_t P1.rollCall(const char* moduleNames[], uint8_t numberOfModules);

Purpose:
Send an array of expected P1 module names to verify connected P1 modules. Module names should be added to the moduleNames array in the same order as the modules (left to right).

Parameters:

Return values:
A 16-bit value that is binary encoded with each bit from LSB to MSB indicating an error (1) or non-error state (0) for the corresponding slot number. A value of 0 indicates no errors.

Function:

void P1.enableBaseController(bool state);

Purpose:
Disables the Base Controller during normal operation and turns off modules. NOTE: To re-enable the Base Controller, call the P1.init() function. Calling P1.enableBaseController(true) will NOT re-init the Base Controller.

Parameters:

Return values:
None.

Channel Labels

The functions below behave the same as the ones described above, but allow for a more descriptive label instead of the “slot” and “channel” values by utilizing the channelLabel structure. This allows you to move your IO devices around and only require a change in one place instead of multiple.

Example:

Instead of performing a P1.readDiscrete(1, 2); you could do the same function as P1.readDiscrete(highLevelSensor_1); with the following code:

channelLabel highLevelSensor_1 = {1,2}; //Create Label for sensor at slot 1 channel 2 bool sensorState = P1.readDiscrete(highLevelSensor_1); //read the sensor

The functions that support this structure are: