Actions

Actions that can be executed to interact with CAD or Aurora Solar.

All actions are asynchronous and return a promise. Use await or .then to handle the resolved value and ensure proper execution order.

downloadScreenshot

Save a screenshot of the current CAD window. The size and resolution will be the same as it is on the current screen. By default, local file download will be triggered for the user with the resulting PNG image. To disable this, set the downloadLocally option to false.

This screenshot is retrievable with the List Assets API endpoint.

Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

await design.downloadScreenshot();

// To prevent a local file download:
await design.downloadScreenshot({ downloadLocally: false });

Signature

downloadScreenshot([options]);

Parameters

parameter	type	note
options	object	Detailed in Options below.

Screenshot Options

name	type	note
downloadLocally	boolean	Enable or disable local file download (defaults to true)

Returns

A promise that resolves when the screenshot has been downloaded and saved to the design.

DownloadScreenshot Errors

message	description
DownloadScreenshot timed out while waiting for map imagery to load	The screenshot function timed out while waiting for map imagery to load. This may be due to a connectivity issue or an issue with the imagery API.

runAutoDesigner

Save a design and run AutoDesigner on it.

runAutoDesigner Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

/**
 * Run AutoDesigner in max fit mode:
 */
const autoDesignerMaxFitOptions = {
  components: {
    solarPanels: ['<solar-panel-id>'],
  },
  mode: 'max_fit',
  placementOptions: {
    orientations: ['landscape'],
  },
},

const maxFitResult = await design.runAutoDesigner(autoDesignerMaxFitOptions);

/**
 * Run AutoDesigner in energy target mode:
 */
const autoDesignerEnergyTargetOptions = {
  mode: 'energy',
  target: 20000,
  components: {
      solarPanels: ['<solar-panel-id>'],
      microInverters: ['<microinverter-id>'],
  },
  placementOptions: {
      orientations: [
            'portrait'
      ]
  }
};

const energyTargetResult = await design.runAutoDesigner(autoDesignerEnergyTargetOptions);

/**
 * Run AutoDesigner in hybrid mode (max fit with an energy target):
 */
const autoDesignerHybridOptions = {
  components: {
    solarPanels: ['<solar-panel-id>'],
  },
  mode: 'max_fit',
  target: 20000,
  placementOptions: {
    orientations: ['landscape'],
  },
},

const maxFitResult = await design.runAutoDesigner(autoDesignerHybridOptions);

runAutoDesigner Signature

runAutoDesigner([options]);

runAutoDesigner Parameters

parameter	type	note
options (required)	object	Detailed in Options below.

runAutoDesigner Returns

A promise that resolves when AutoDesigner has completed.

AutoDesigner Options

There are currently 3 mode options available for AutoDesigner:

• max_fit: Places the maximum number of panels possible within the constraints passed in through placement_options.

  • Only takes solarPanels in the components input option, will ignore other components such as inverters.
  • You may optionally attach a microinverter to all panels by specifying one in your tenant settings (the "Add Microinverters" field in the Aurora Solar App admin settings.

• energy: Places components to generate energy production that is as close as possible to the provided energy target (in kWh) within the constraints passed in through placementOptions.

• hybrid: When specifying both mode: "max_fit" and an energy target, the algorithm will attempt to place the maximum number of panels possible within the constraints passed in through placementOptions, and then disable any panels that are not needed to meet the energy target.

name	type	note
components (required)	object	Detailed in AutoDesigner Components below
mode	string	The optimization mode, choose between ["max_fit", "energy"].
target	number	Target energy, in kWh. Can be used in either mode.
placementOptions	object	Detailed in Placement Options below

AutoDesigner Components

Note that in max-fit mode, inverters specified via the components object are not used.

In order to find the IDs for components to use, you need to use the Aurora application.

Go to the Aurora database page for a list of all components, or for specific types, see the following pages:

• Solar Panels
• Inverters / Micro Inverters
• DC Optimizers

We also provide a utility method within the SDK for getting a list of your tenant's "starred/checked" components within the database pages. See this page on fetching Components for more details.

name	type	note
dcOptimizers	Array<string>	Array of DC Optimizer IDs to use within design
stringInverters	Array<string>	Array of String Inverter IDs to use within design
microInverters	Array<string>	Array of Micro Inverter IDs to use within design
solarPanels	Array<string>	Array of Solar Panel IDs to use within design

Placement Options

name	type	note
allowFillerRow	boolean	Allow a row of panels with opposite orientation on top or bottom of the panel layout if it improves the result.
columnSpacingMeters	number	Distance between columns of panels, in meters. Default 0.
flatFaceColumnSpacingMeters	number	Distance between columns of panels, in meters, when a roof face is below the threshold to consider it pitched. Default 0.
flatFaceOrientations	Array<string>	Allowable orientations of panels when a roof face is below the threshold to consider it pitched. May contain any combination of ["portrait", "landscape"].
flatFacePanelTiltDegrees	number	The tilt of panels relative to the roof surface, in degrees. Applies to flat roof faces. Minimum 0, maximum 80 degrees. Default 0.
flatFaceRowSpacingMeters	number	Distance between rows of panels, in meters, when a roof face is below the threshold to consider it pitched. Default 0.
minAzimuthDegrees	number	The minimum roof azimuth upon which panels are allowed to be placed, where 0 is north and 180 is south.
maxAzimuthDegrees	number	The maximum roof azimuth upon which panels are allowed to be placed, where 0 is north and 180 is south.
minContiguousPanels	number	Minimum number of contiguous panels in every row. Mode must be energy for this option.
minSap	number	Minimum solar access percentage of panels, expressed as a decimal between 0 and 1. Default 0.
minTsrf	number	Minimum total solar resource fraction of panels, expressed as a decimal between 0 and 1. Default 0.
panelTiltDegrees	number	The tilt of panels relative to the roof surface, in degrees. Applies to pitched roof faces. Minimum 0, maximum 80 degrees. Default 0.
pitchedFaceTiltThresholdDegrees	number	Azimuth threshold above which a roof face is considered pitched, in degrees. Minimum 0, maximum 80 degrees. Default 0.*
orientations	Array<string>	Allowable orientations of panels. May contain any combination of ["portrait", "landscape"].
rowSpacingMeters	number	Distance between rows of panels, in meters. Default 0.

* If this option is set to 0, a roof face with a pitch of 0 degrees will still be considered flat. Anything greater than 0 will be pitched.

AutoDesigner Errors

message	description
Could not place panels meeting specified SAP, TSRF thresholds	The roof model is not adequate to to standards set in the placement options. If the roof model seems accurate, this issue could be addressed by adjusting the placement options.
Roof is too small to place any panels	This error may occur if a broken roof model is created. Try re-running AI Roof with the clear parameter to resolve this issue if it happens intermittently.
Invalid AutoDesigner options	The format of the placement options is incorrect, or a required option is missing.

runAutoStringer

Automatically string together a group of panels, connect them to an inverter(s), and save the design.

Specify either 1-3 string inverters and an optional DC optimizer or 1-3 microinverters. AutoStringer will choose the best combination of components for your site and panels. The components you choose already have DC/AC Ratio and Max/Min string lengths set as properties, but you can override them if you choose.

Note that this action will remove all existing strings and inverters in the design before placing new ones. Also, it will automatically toggle off any panels that could not be strung due to electrical constraints.

runAutoStringer Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.create(projectId, 'Design Name');

// Specify up to 3 inverters:
await design.runAutoStringer({
  components: {
    dcOptimizers: ['dc-optimizer-id'], // optional
    stringInverters: ['string-inverter-id-1', 'string-inverter-id-2', 'string-inverter-id-3'],
  },
});

// Optionally override default electrical parameters for the inverters by passing them as an object with the specified keys
await design.runAutoStringer({
  components: {
    dcOptimizers: ['dc-optimizer-id'], // optional
    stringInverters: [
      'string-inverter-id-1',
      {
        id: 'string-inverter-id-2',
        dcAcRatio: 1.2,
        maxStringLength: 10,
        minStringLength: 4,
      },
      'string-inverter-id-3',
    ],
  },
});

// Use microinverters rather than string inverters. These do not accept overrides:
await design.runAutoStringer({
  components: {
    dcOptimizers: ['dc-optimizer-id'], // optional
    microInverters: ['microinverter-id-1', 'microinverter-id-2', 'microinverter-id-3'],
  },
});

runAutoStringer Signature

runAutoStringer(options);

runAutoStringer Parameters

parameter	type	note
options	object	Detailed in Options below.

runAutoStringer Returns

A promise which resolves when AutoStringer has finished. The promise may reject with an error message if AutoStringer fails.

AutoStringer Options

name	type	note
components	object	Detailed in AutoStringer Components below.

AutoStringer Components

name	type	note
dcOptimizers	Array<string>	Array of DC Optimizer IDs to use within design. Optional.
stringInverters	Array<string> or Array<object>	Array of String Inverter IDs or override objects to use within design. See AutoStringer Overrides below.
microInverters	Array<string>	Array of Micro Inverter IDs to use within design

Note that only one of stringInverters or microInverters may be specified, with up to 3 inverter components. Note that users must specify at least one inverter component. DC optimizers are optional.

AutoStringer Overrides

Except for the component id, any of these override parameters may be left undefined to use a default value which differs based on the component used.

name	type	note
id	string	ID of the inverter to use within design. Required.
dcAcRatio	number	DC/AC ratio of the inverter. Leave undefined to use the default value for this component.
maxStringLength	number	Maximum number of panels to string together. Leave undefined to use the default value for this component.
minStringLength	number	Minimum number of panels to string together. Leave undefined to use the default value for this component.

AutoStringer Errors

message	description
Component ID not found in database	Check to make sure you are using correct Component ID.
Too many DC optimizers. 0 or 1 required	Check to make sure you are not passing in more than 1 DC optimizer.
Cannot request both DC optimizers and microinverters	AutoStringer can only accept either DC optimizers or microinverters on a given run.
Cannot request both string inverters and microinverters	AutoStringer can only accept either string inverters or microinverters on a given run.
Not enough inverters (minimum: 1 string inverter or 1 microinverter)	Make sure you submit at least 1 inverter.
Too many string inverters (maximum: 3)	AutoStringer cannot accept more than 3 string inverters.
Too many microinverters (maximum: 3)	AutoStringer cannot accept more than 3 microinverters.
Selected solar panels already have integrated microinverters	The selected solar panels already have an integrated microinverters. Include only string inverters as input to AutoStringer.
Selected solar panels already have integrated optimizers	The selected solar panels already have an integrated optimizer. Include only string inverters as input to AutoStringer.
Too many solar panel models selected (maximum: 1)	AutoStringer can string only one panel model at once.
Not enough solar panels (minimum: 2)	AutoStringer requires at least 2 solar panels.
String to inverter assignment ILP failed	String inverter and DC Optimizer are incompatible. Choose different components.

runAutoRoof

Run AI Roof on a design and save it.

runAutoRoof Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.create(projectId, 'Design Name');

const result = await design.runAutoRoof();

// To clear system design and roof models before running AI Roof:
const result = await design.runAutoRoof({ clear: true });

runAutoRoof Signature

runAutoRoof(options);

runAutoRoof Parameters

parameter	type	note
options	object	Detailed in Options below.

runAutoRoof Returns

A promise which resolves when AI Roof has finished. The promise may reject with an error message if AI Roof fails.

AutoRoof Options

name	type	note
clear	boolean	Clear existing system design and roofs prior to running AI Roof
skipOodLidar	boolean	Ignore Lidar Out of Date errors and continue creating a roof model

AI Roof Errors

message	description
LIDAR/HD imagery not available	Imagery is not yet available for this address and AI Roof will not be able to model a roof. Ensure that the address (pin) for the design is accurate. In the Aurora App, toggle the type of imagery to see if a different type is available.
Unknown error occured	An unknown AI Roof error occurred. This may be resolved in some instances by the same means as the "LIDAR/HD imagery not available" error.
Lidar Out of Date	The LIDAR imagery for this site does not align with the map imagery, and AI Roof models would be inaccurate. A roof for this site must be created manually.
AI won't work for this site	An error occurred with the AI roof algorithm. A roof for this site must be created manually.
No imagery chosen	There is no imagery type chosen for this design, or the imagery failed to load. It may be addressed by re-creating the project or design from scratch after ensuring that an imagery type is selected in the Aurora App.

runIrradiance

Save a design, then run roof and panel irradiance analysis on it. The analysis will update irradiance maps visible in the CAD screen and shading data in the design summary available via Aurora REST API.

runIrradiance Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

const result = await design.runIrradiance();

runIrradiance Signature

runIrradiance(options?: Options);

runIrradiance Parameters

The options object has properties that are as follows:

name	type	notes
timeoutMs	number	Time to wait before failing the action, in milliseconds. Default is 120,000 ms (two minutes).

runIrradiance Returns

A promise which returns when irradiance has finished calculating.

The promise wraps an object including some shading data:

name	type	notes
irradiance	number	Average irradiance
solarAccess	number	Average solar access percentile
tsrf	number	Total Solar Resource Fraction

Irradiance Errors

message	description
Irradiance Error: (message)	An error has occured in the irradiance service; the message will specify the cause of the error or 'Unknown Error'
Irradiance cannot be run	The irradiance job cannot be started, most likely because the current irradiance maps are still valid

Viewing Irradiance Maps

The irradiance maps must be toggled on using the toggleView API before using the runIrradiance method in order to guarantee the data will be populated.

In addition, toggling on the irradiance map texture for panels will automatically run the irradiance analysis job if the data is stale.

runPerformanceSimulation

Save a design and run performance simulation on it.

The action simulates the operation of the system and determines its energy production. It also accounts for the impact of shading from buildings, trees, and obstructions. Performance simulation is a self-contained action that doesn't depend on other Client SDK actions such as runIrradiance.

runPerformanceSimulation Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

const result = await design.runPerformanceSimulation();

runPerformanceSimulation Signature

runPerformanceSimulation();

runPerformanceSimulation Returns

A promise which resolves with the following object when the performance simulation has finished.

name	type	note
annual	number	Total annual energy production
monthly	Array<number>	Energy production broken down by month

startSunAnimation

The animation begins at noon on the summer solstice, which is June 21 and Dec 22 for projects with addresses in Northern and Southern Hemisphere, respectively.

The startSunAnimation method can take a parameter indicating the animation mode. This changes the path the sun will animate on. Valid parameters include 'month' and 'hour'.

The animation mode will default to 'month' if no parameter is provided.

startSunAnimation Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

design.startSunAnimation();

startSunAnimation Signature

startSunAnimation(animationMode);

startSunAnimation Returns

Promise<void>

stopSunAnimation

stopSunAnimation Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

design.stopSunAnimation();

stopSunAnimation Signature

stopSunAnimation();

stopSunAnimation Returns

Promise<void>

Undo/Redo

Undo/Redo Usage

const library = await import('<script_url>');
const sdk = await library.load({ token: '<access_token>' });
const design = await sdk.design.load(designId);

design.undo();
design.redo();

Undo/Redo Signature

undo();
redo();

Undo/Redo Returns

Promise<void>

modifySolarPanels

Disable, enable, and remove solar panels in the design based on their position on a roof face.

The method expects a callback function, which is provided with a panel layout as input. The panel layout contains all the roof-based panels in the design grouped by their roof face. Each panel contains roof position information as well as methods to modify them. Calling a panel's modify methods (disable(), enable(), remove()) marks that panel for modification. All modifications are applied together and saved after the callback function resolves. The method returns a promise that contains the total counts of all of the panels that were modified.

modifySolarPanels Usage

const result = await design.modifySolarPanels((layout) => {
  // The layout contains an array of roof faces.
  layout.roofFaces.forEach((roofFace) => {
    // Each roof face contains an array of panels
    const panel = roofFace.panels[0];

    // Use the panel's position on the roof to determine if it should be modified
    if (panel.roofFaceX > 10) {
      panel.disable();
    } else {
      panel.remove();
    }
  });
});

modifySolarPanels signature

const modifiedTotals = await design.modifySolarPanels(callback);

modifySolarPanels Parameters

name	type	note
callback	function	A function (or async function) that receives a panel layout that can be used to modify panels. When this function resolves, the layout becomes obsolete.

modifySolarPanels Returns

The method returns a Promise that resolves with the total numbers of modified panels. If panels that were already enabled are marked to be enabled they will not be modified and therefore not be reflected in the totals. Likewise, disabled panels marked to be disabled will not be reflected in the totals.

type ModifySolarPanelResponse = Promise<{
  panelsDisabled: number;
  panelsEnabled: number;
  panelsRemoved: number;
}>;

modifySolarPanels Callback

A function or async function that is passed a ModifySolarPanelsLayout object. The layout provides panels grouped by their roof faces. Each panel contains positioning information as well as methods to modify the panel.

Once this function finishes executing, or once the promise it returns has been resolved, all of the modifications will be applied to the design together, the design will be saved, and the layout will become obsolete.

type ModifySolarPanelsCallback = (layout: ModifySolarPanelsLayout) => void | Promise<void>;

modifySolarPanels Layout Object

The layout is a snapshot representation of the current panels in the design. It contains all of the roof-based panels grouped by their roof face. Only roof faces that contain panels will be included.

After the callback resolves and the modifications are applied to the design, the layout will no longer be current, and the panel methods will no longer work. Because of this, the layout should never be stored between calls to this design method.

type ModifySolarPanelsLayout = {
  roofFaces: {
    panels: ModifySolarPanelsPanel[];
  };
};

modifySolarPanels Panel Object

Each panel contains information about its size and position on the roof face. Panels can be marked for modification with their disable() enable() or remove() methods. Once the callback resolves, the panel’s methods can no longer be called and will throw an error.

parameter	type	description
roofFaceX	number (meters) or null	The x coordinate of the panel's center on the roof plane. It will be null if the panel is rotated or tilted.
roofFaceY	number (meters) or null	The y coordinate of the panel's center on the roof plane. It will be null if the panel is rotated or tilted.
height	number (meters)	The vertical height of the panel on the roof plane
width	number (meters)	The horizontal width of the panel on the roof plane
isEnabled	boolean	Whether the panel is currently enabled.
enable	function	A method called to mark a panel to be enabled after the callback resolves
disable	function	A method called to mark a panel to be disabled after the callback resolves
remove	function	A method called to mark a panel to be removed after the callback resolves

type ModifySolarPanelsPanel = {
  roofFaceX: number | null;
  roofFaceY: number | null;
  height: number;
  width: number;
  isEnabled: boolean;
  enable: () => void;
  disable: () => void;
  remove: () => void;
};