# System
[Core]

The System subsystem monitors and controls several aspects of the system. More...

## Functions
int | System_SetActive (int state)
| Sets whether the System subsystem is active.
int | System_GetActive ()
| Returns the active state of the subsystem.
int | System_GetFreeMemory (void)
| Returns the free size of the heap.
int | System_GetSerialNumber (void)
| Gets the board's Serial Number.
int | System_SetSerialNumber (int serial)
| Sets the Serial Number.
int | System_SetSamba (int sure)
| Returns the board to SAM-BA mode.
int | System_SetName (char *name)
| Gives the board a name.
char * | System_GetName ()
| Read the board's name.
int | System_SetReset (int sure)
| Reset the board.

## Detailed Description

The System subsystem monitors and controls several aspects of the system.

## Function Documentation

int System_GetActive | ( | void |  | ) |

Returns the active state of the subsystem.

Returns:
  The active state of the subsystem - 1 (active) or 0 (inactive).

Example

      if(System_GetActive())
      {
        // System is active
      }
      else
      {
        // System is inactive
      }

Definition at line 127 of file system.c.

int System_GetFreeMemory | ( | void |  | ) |

Returns the free size of the heap.

The heap size is set in config.h in the constant CONTROLLER_HEAPSIZE. Any calls to Malloc will take their memory from the heap. This allows you to check how much heap is remaining.

Returns:
  The size free memory.

Example

      // see how much memory is available
      int freemem = System_GetFreeMemory();

Definition at line 145 of file system.c.

char* System_GetName | ( | void |  | ) |

Read the board's name.

Returns:
  The board's name as a string.

Example

      char* board_name = System_GetName();

Definition at line 345 of file system.c.

int System_GetSerialNumber | ( | void |  | ) |

Gets the board's Serial Number.

Each board has a serial number, although it's not necessarily unique as you can reset it as you please.

The serial number is used to determine the Ethernet MAC address, so boards on the same network need to have unique serial numbers.

Returns:
  CONTROLLER_OK ( = 0 ).

Example

      // get this board's serial number
      int sernum = System_GetSerialNumber();

Definition at line 165 of file system.c.

int System_SetActive | ( | int | state | ) |

Sets whether the System subsystem is active.

Parameters:

  | state | An integer specifying the state system

Returns:
  Zero on success.

Example

      // enable the System subsystem
      System_SetActive(1);

Definition at line 82 of file system.c.

int System_SetName | ( | char * | name | ) |

Gives the board a name.

The name must be alpha-numeric - only letters and numbers. It can help you determine one board from another when there are more than one connected to your system.

Parameters:

  | name | A string specifying the board's name

Returns:
  0 on success.

Example

      // give the board a special name
      System_SetName("my very special controller");

Definition at line 318 of file system.c.

int System_SetReset | ( | int | sure | ) |

Reset the board.

Will reboot the board if the parameter sure is true.

Parameters:

  | sure | confirms the request is true.

Returns:
  0 on success.

Example

      // reboot
      System_SetReset(1);

Definition at line 393 of file system.c.

int System_SetSamba | ( | int | sure | ) |

Returns the board to SAM-BA mode.

When a board is in SAM-BA mode, it is ready to have new firmware uploaded to it. Upon successful completion, the board will be reset and begin running SAM-BA. This function does not clear the GPNVM2 bit, so if you unplug/replug you'll be running your old code again.

Parameters:

  | sure | Confirm you're sure you want to do this.

Returns:
  nonzero on failure. Successful completion does not return.

Example

      // prepare to be uploaded
      System_SetSamba(1);

Definition at line 208 of file system.c.

int System_SetSerialNumber | ( | int | serial | ) |

Sets the Serial Number.

Note that this can be changed by the user at any time, but that it is used in the Network subsystem to form the last two bytes of the network MAC address, so ideally units on the same network should have unique serial numbers.

Returns:
  0 on success.

Example

      // set the serial number to 12345
      System_SetSerialNumber(12345);

Definition at line 187 of file system.c.