Bug: Documentation incorrectly instructs calling super().startup() and super().shutdown()

[simons-plugins]

Bug: Documentation incorrectly instructs calling super().startup() and super().shutdown()

Summary

The Indigo skill documentation contains incorrect guidance that tells developers to call super().startup() and super().shutdown() in their plugin code. These methods do not exist in indigo.PluginBase, causing AttributeError exceptions when developers follow the documentation.

Impact

Severity: High - Breaks all plugins created using the documentation/templates

Affected Components:

• ❌ snippets/plugin-base-template.py - Template code had super().startup() and super().shutdown()
• ❌ docs/concepts/plugin-lifecycle.md - Multiple examples showing incorrect super() calls
• ❌ docs/quick-start.md - "Common Mistakes" section showed wrong pattern
• ❌ docs/troubleshooting/README.md - Debug examples had super() calls

The Problem

What the Documentation Said (WRONG)

def startup(self):
    super().startup()  # AttributeError: 'super' object has no attribute 'startup'
    self.logger.info("Starting")

def shutdown(self):
    self.logger.info("Stopping")
    super().shutdown()  # AttributeError: 'super' object has no attribute 'shutdown'

What the SDK Examples Actually Do (CORRECT)

Checked all 16 official SDK examples - ZERO call super().startup() or super().shutdown():

$ grep -r "super().startup\|super().shutdown" sdk-examples/ --include="*.py"
# No matches found

Examples:

• Example Device - Sprinkler: def startup(self): pass (no super)
• Example Device - Custom: def startup(self): self.logger.debug("startup called") (no super)
• All other examples: No super() calls in startup/shutdown

Root Cause

The documentation was written incorrectly without validating against the official SDK examples. The methods startup() and shutdown() are pure callbacks with no parent implementation in indigo.PluginBase.

Error Produced

When developers follow the documentation, they get:

Error in plugin execution startup:
File "plugin.py", line 43, in startup
type: 'super' object has no attribute 'startup'

Which Methods Actually Need super()?

Method	Needs super()?	Required?
__init__()	✅ YES	REQUIRED - super().__init__(...)
startup()	❌ NO	Do NOT call super()
shutdown()	❌ NO	Do NOT call super()
deviceStartComm()	✅ YES	Recommended - super().deviceStartComm(dev)
deviceStopComm()	✅ YES	Recommended - super().deviceStopComm(dev)
deviceUpdated()	✅ YES	Recommended - super().deviceUpdated(origDev, newDev)
variableUpdated()	✅ YES	Recommended - super().variableUpdated(origVar, newVar)

The Fix

Correct Pattern

def startup(self):
    # Note: Do NOT call super().startup() - it doesn't exist
    self.logger.info(f"{self.pluginDisplayName} starting")
    # Initialize API clients, subscribe to events, etc.

def shutdown(self):
    # Note: Do NOT call super().shutdown() - it doesn't exist
    self.logger.info(f"{self.pluginDisplayName} shutting down")
    # Clean up resources, close connections, etc.

Files Fixed

1. snippets/plugin-base-template.py

   • Removed super().startup() call
   • Removed super().shutdown() call
   • Added clarifying comments

2. docs/concepts/plugin-lifecycle.md

   • Fixed "Rules" section to say "Do NOT call super()"
   • Fixed 8+ code examples showing incorrect super() calls
   • Replaced "Forgetting to Call super()" section with "Calling super() in Wrong Methods"
   • Added notes to all startup/shutdown examples

3. docs/quick-start.md

   • Replaced "Common Mistake Welcome to indigo-claude-skill Discussions! #1" with correct guidance
   • Added table showing which methods need super()

4. docs/troubleshooting/README.md

   • Fixed debug example that showed super().startup()

5. docs/troubleshooting/common-issues.md

   • Added new troubleshooting section for AttributeError
   • Added clear table of which methods need super()
   • Added API URL construction best practices

Testing

Created a test Netro sprinkler plugin following the OLD documentation:

• ❌ Before fix: Plugin crashed with AttributeError: 'super' object has no attribute 'startup'
• ✅ After fix: Plugin starts and shuts down correctly

References

• Official SDK Examples: All 16 examples in sdk-examples/ directory
• Official Indigo Docs: https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:plugin_guide
• Real-world impact: Netro plugin development session where this bug was discovered

Lesson Learned

Always validate documentation against official SDK examples before adding it to community resources. The SDK examples are the source of truth.